{"_id":"56631b1bcd54d50d005015f5","category":{"_id":"56c77749b935671700ff0304","__v":6,"pages":["56c777aec2f82e0d00d7cfc4","56cf5f668629f91300fd97ce","56d00c374a03c00b00a07c03","56d3b713d3f4650b00749658","56d3d74fd3f4650b00749677","56d3d9d20b39260b008da47b"],"project":"564e5930c3553e0d003e53d0","version":"564e5a9b1560880d008d30dc","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-02-19T20:12:57.931Z","from_sync":false,"order":5,"slug":"events-api","title":"Events API v1"},"user":"564e5788230d7c1700c9073e","__v":25,"githubsync":"","project":"564e5930c3553e0d003e53d0","parentDoc":null,"version":{"_id":"564e5a9b1560880d008d30dc","project":"564e5930c3553e0d003e53d0","__v":26,"createdAt":"2015-11-19T23:26:19.166Z","releaseDate":"2015-11-19T23:26:19.166Z","categories":["564e5a9b1560880d008d30dd","566318e1f5ca460d00f41896","56631d08cd54d50d005015fa","56631d2a81ad7417006a202c","5668ba19fbd7680d009375f4","5668cb8b10bda80d00797ed9","5668cb9d10bda80d00797eda","56830d8a3f94e00d004e2a7a","56830d9072bb720d0091f594","56830d94cb4d190d0027698e","56830dc44aecbd0d00a464c5","569e90f3c9b43e0d00c4bab1","56a96d338791090d00113bab","56b12d8336d2580d00247877","56c36bf0a869d017002ea55b","56c36bf93d30210d00ea84bb","56c77749b935671700ff0304","56c7ab9e5652c217008e091a","56cb8bdad5c6241d00ef5e61","58aefce02470660f00b54539","58aefd0bebd7370f0078b954","59ca65ca4337830026edf24f","5c33cd9eb47ba20051ac8d64","5c33df728bec1d0063431c34","5c4783ef523219027055513a","5c4f35033400f3010203a999"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"Foundation","version_clean":"2.0.0","version":"2"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-12-05T17:12:59.155Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"The PagerDuty Events API is used to add PagerDuty's advanced incident management functionality to any system that can make an HTTP API call. You can now add phone, SMS, email, and mobile push notifications to your monitoring tools, ticketing systems, and custom software.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Description\"\n}\n[/block]\nEvents API v1 was designed to allow you to easily integrate a monitoring system with a [service](https://support.pagerduty.com/docs/services-and-integrations) in PagerDuty. Monitoring systems generally send out events when problems are detected and when these problems have been resolved (fixed). Some more advanced systems also understand the concept of acknowledgements: problems can be acknowledged by an engineer to signal that he or she is working on fixing the issue.\n\nSince monitoring systems emit events, the Events API is based around accepting events. Incoming events are routed to a PagerDuty service and processed. They may result in a new incident being created, or an existing incident being acknowledged or resolved.\n\nThe same event-based API can also be used to integrate a PagerDuty service with ticketing systems and various other software tools.\n\nTo accomplish customized integrations with PagerDuty, you may be interested in [becoming PagerDuty partner](https://pdconnect.wufoo.com/forms/become-a-pagerduty-technology-partner/).\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Getting Started\"\n}\n[/block]\nThe Events API can be used with any service that has an Events API v1 integration, or by [creating a new service or integration](https://support.pagerduty.com/docs/services-and-integrations#section-create-a-generic-events-api-integration) with the option **Use our API directly**.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Making a Request\"\n}\n[/block]\nTo make an Events API v1 request, POST a JSON body (size limited to **512 KB**) representing the event to the following URL:\n\n```\nhttps://events.pagerduty.com/generic/2010-04-15/create_event.json\n```\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Note\",\n  \"body\": \"`2010-04-15` is a version identifier. Do not change the URL to today's date, or any other date.\"\n}\n[/block]\nHead on over to [Create Event](doc:trigger-events) to see the full details of the event body format and to send an event to PagerDuty right from the documentation. \n[block:callout]\n{\n  \"type\": \"success\",\n  \"body\": \"Want a simpler way to send events to PagerDuty? The [PagerDuty Agent](https://www.pagerduty.com/docs/guides/agent-install-guide/) provides an installable command-line utility for Linux-based systems that handles all the details of event queueing and sending.\",\n  \"title\": \"Tip\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Event Types\"\n}\n[/block]\nThere are three types of events that PagerDuty recognizes, and are used to represent different types of activity in your monitored systems.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Event Type\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"`trigger`\",\n    \"1-0\": \"`acknowledge`\",\n    \"2-0\": \"`resolve`\",\n    \"0-1\": \"When PagerDuty receives a `trigger` event, it will either open a new incident, or add a new trigger log entry to an existing incident, depending on the provided `incident_key`.\\n\\nIf there is no one on call for the service's escalation policy when the event is triggered, an incident will not be created.\\n\\nYour monitoring tools should send PagerDuty a `trigger` event to report a new or ongoing problem.\",\n    \"1-1\": \"`acknowledge` events cause the referenced incident to enter the acknowledged state.\\n\\nWhile an incident is acknowledged, it won't generate any additional notifications, even if it receives new trigger events.\\n\\nYour monitoring tools should send PagerDuty an `acknowledge` event when they know someone is presently working on the problem.\",\n    \"2-1\": \"`resolve` events cause the referenced incident to enter the resolved state.\\n\\nOnce an incident is resolved, it won't generate any additional notifications. New trigger events with the same `incident_key` as a resolved incident won't re-open the incident. Instead, a new incident will be created.\\n\\nYour monitoring tools should send PagerDuty a `resolve` event when the problem that caused the initial trigger event has been fixed.\"\n  },\n  \"cols\": 2,\n  \"rows\": 3\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Incident De-duplication and incident_key\"\n}\n[/block]\nEvery incident has an `incident_key`: a string which identifies the incident. The `incident_key` can be specified when submitting the first `trigger` event that creates an incident. If omitted, it will be generated automatically by PagerDuty and returned in the Events API response.\n\nSubmitting subsequent events for the same `incident_key` will result in those events being applied to an open incident matching that `incident_key`. Once the incident is `resolved`, any further events with the same `incident_key` will create a new incident (for `trigger` events) or be dropped (for `acknowledge` and `resolve` events).\n\nSubsequent events for the same `incident_key` will only apply to the open incident if the events are sent via the same `service_key` as the original `trigger` event. Subsequent `acknowledge` or `resolve` events sent via a different `service_key` from the original will be dropped. Incidents created within the PagerDuty web application are inaccessible via the Events API.\n\nIf a `trigger` event is sent with no `incident_key`, it will always generate a new incident because the key is [a UUID](doc:types#uuid).\n[block:api-header]\n{\n  \"title\": \"API Response Codes & Retry Logic\"\n}\n[/block]\nThe following table shows the possible results of the API request and if you need to retry the API call for that result:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Result\",\n    \"h-1\": \"Description\",\n    \"h-2\": \"Retry?\",\n    \"0-0\": \"200\",\n    \"0-1\": \"Event was received and processed successfully\",\n    \"0-2\": \"No\",\n    \"1-0\": \"400\",\n    \"1-1\": \"Invalid event format (i.e. JSON parse error) or incorrect event structure\",\n    \"1-2\": \"No\",\n    \"2-0\": \"403\",\n    \"2-1\": \"Rate limit reached (too many Events API requests)\",\n    \"2-2\": \"Yes - retry after some time\",\n    \"3-1\": \"Internal Server Error - the PagerDuty server experienced an error while processing the event.\",\n    \"3-0\": \"500 or other 5XX\",\n    \"3-2\": \"Yes - retry after some time\",\n    \"4-1\": \"Error while trying to communicate with PagerDuty servers.\",\n    \"4-2\": \"Yes - retry after some time\",\n    \"4-0\": \"Network Error\"\n  },\n  \"cols\": 3,\n  \"rows\": 5\n}\n[/block]","excerpt":"","slug":"events-api","type":"basic","title":"Events API v1 Overview"}

Events API v1 Overview


The PagerDuty Events API is used to add PagerDuty's advanced incident management functionality to any system that can make an HTTP API call. You can now add phone, SMS, email, and mobile push notifications to your monitoring tools, ticketing systems, and custom software. [block:api-header] { "type": "basic", "title": "Description" } [/block] Events API v1 was designed to allow you to easily integrate a monitoring system with a [service](https://support.pagerduty.com/docs/services-and-integrations) in PagerDuty. Monitoring systems generally send out events when problems are detected and when these problems have been resolved (fixed). Some more advanced systems also understand the concept of acknowledgements: problems can be acknowledged by an engineer to signal that he or she is working on fixing the issue. Since monitoring systems emit events, the Events API is based around accepting events. Incoming events are routed to a PagerDuty service and processed. They may result in a new incident being created, or an existing incident being acknowledged or resolved. The same event-based API can also be used to integrate a PagerDuty service with ticketing systems and various other software tools. To accomplish customized integrations with PagerDuty, you may be interested in [becoming PagerDuty partner](https://pdconnect.wufoo.com/forms/become-a-pagerduty-technology-partner/). [block:api-header] { "type": "basic", "title": "Getting Started" } [/block] The Events API can be used with any service that has an Events API v1 integration, or by [creating a new service or integration](https://support.pagerduty.com/docs/services-and-integrations#section-create-a-generic-events-api-integration) with the option **Use our API directly**. [block:api-header] { "type": "basic", "title": "Making a Request" } [/block] To make an Events API v1 request, POST a JSON body (size limited to **512 KB**) representing the event to the following URL: ``` https://events.pagerduty.com/generic/2010-04-15/create_event.json ``` [block:callout] { "type": "info", "title": "Note", "body": "`2010-04-15` is a version identifier. Do not change the URL to today's date, or any other date." } [/block] Head on over to [Create Event](doc:trigger-events) to see the full details of the event body format and to send an event to PagerDuty right from the documentation. [block:callout] { "type": "success", "body": "Want a simpler way to send events to PagerDuty? The [PagerDuty Agent](https://www.pagerduty.com/docs/guides/agent-install-guide/) provides an installable command-line utility for Linux-based systems that handles all the details of event queueing and sending.", "title": "Tip" } [/block] [block:api-header] { "type": "basic", "title": "Event Types" } [/block] There are three types of events that PagerDuty recognizes, and are used to represent different types of activity in your monitored systems. [block:parameters] { "data": { "h-0": "Event Type", "h-1": "Description", "0-0": "`trigger`", "1-0": "`acknowledge`", "2-0": "`resolve`", "0-1": "When PagerDuty receives a `trigger` event, it will either open a new incident, or add a new trigger log entry to an existing incident, depending on the provided `incident_key`.\n\nIf there is no one on call for the service's escalation policy when the event is triggered, an incident will not be created.\n\nYour monitoring tools should send PagerDuty a `trigger` event to report a new or ongoing problem.", "1-1": "`acknowledge` events cause the referenced incident to enter the acknowledged state.\n\nWhile an incident is acknowledged, it won't generate any additional notifications, even if it receives new trigger events.\n\nYour monitoring tools should send PagerDuty an `acknowledge` event when they know someone is presently working on the problem.", "2-1": "`resolve` events cause the referenced incident to enter the resolved state.\n\nOnce an incident is resolved, it won't generate any additional notifications. New trigger events with the same `incident_key` as a resolved incident won't re-open the incident. Instead, a new incident will be created.\n\nYour monitoring tools should send PagerDuty a `resolve` event when the problem that caused the initial trigger event has been fixed." }, "cols": 2, "rows": 3 } [/block] [block:api-header] { "type": "basic", "title": "Incident De-duplication and incident_key" } [/block] Every incident has an `incident_key`: a string which identifies the incident. The `incident_key` can be specified when submitting the first `trigger` event that creates an incident. If omitted, it will be generated automatically by PagerDuty and returned in the Events API response. Submitting subsequent events for the same `incident_key` will result in those events being applied to an open incident matching that `incident_key`. Once the incident is `resolved`, any further events with the same `incident_key` will create a new incident (for `trigger` events) or be dropped (for `acknowledge` and `resolve` events). Subsequent events for the same `incident_key` will only apply to the open incident if the events are sent via the same `service_key` as the original `trigger` event. Subsequent `acknowledge` or `resolve` events sent via a different `service_key` from the original will be dropped. Incidents created within the PagerDuty web application are inaccessible via the Events API. If a `trigger` event is sent with no `incident_key`, it will always generate a new incident because the key is [a UUID](doc:types#uuid). [block:api-header] { "title": "API Response Codes & Retry Logic" } [/block] The following table shows the possible results of the API request and if you need to retry the API call for that result: [block:parameters] { "data": { "h-0": "Result", "h-1": "Description", "h-2": "Retry?", "0-0": "200", "0-1": "Event was received and processed successfully", "0-2": "No", "1-0": "400", "1-1": "Invalid event format (i.e. JSON parse error) or incorrect event structure", "1-2": "No", "2-0": "403", "2-1": "Rate limit reached (too many Events API requests)", "2-2": "Yes - retry after some time", "3-1": "Internal Server Error - the PagerDuty server experienced an error while processing the event.", "3-0": "500 or other 5XX", "3-2": "Yes - retry after some time", "4-1": "Error while trying to communicate with PagerDuty servers.", "4-2": "Yes - retry after some time", "4-0": "Network Error" }, "cols": 3, "rows": 5 } [/block]