{"__v":24,"_id":"56631b1bcd54d50d005015f5","category":{"__v":6,"_id":"56c77749b935671700ff0304","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":2,"slug":"events-api","title":"Events API v1"},"parentDoc":null,"project":"564e5930c3553e0d003e53d0","user":"564e5788230d7c1700c9073e","version":{"__v":21,"_id":"564e5a9b1560880d008d30dc","project":"564e5930c3553e0d003e53d0","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"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"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":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","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]\nThis API was designed to allow you to easily integrate a monitoring system with a Service 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 API is based around accepting events. Incoming events (sent via the API) 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](doc:become-a-pagerduty-partner).\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Getting Started\"\n}\n[/block]\nThe Events API can be used with any \"Generic API\" integration in PagerDuty. If you don't already have a \"Generic API\" integration, you [should create one](https://support.pagerduty.com/hc/en-us/articles/202830340-Creating-a-Generic-API-Service):\n\nFor creating a new Service with a \"Generic API\" integration: \n1. In your account, under the Services tab, click \"Add New Service\".\n2. Select \"Use our API Directly\" from the Integration Type menu and enter in an Integration Name.\n2. Enter a name for the service and select an escalation policy.\n3. Click the \"Add Service\" button.\n4. Once the service is created, you'll be taken to the Integrations tab for that service. On this page, you'll see the \"Integration key\", which is referred to as \"service_key\" in our API documentation, and is needed to access the API.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Making a Request\"\n}\n[/block]\nTo make an API request, POST a JSON body representing the event to\n\n```\nhttps://events.pagerduty.com/generic/2010-04-15/create_event.json\n```\n\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\": \"info\",\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}\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 `integration_key` as the original `trigger` event. Subsequent `acknowledge` or `resolve` events sent via a different `integration_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).","excerpt":"Using the Events API to send events to PagerDuty","slug":"events-api","type":"basic","title":"Overview"}

Overview

Using the Events API to send events to PagerDuty

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] This API was designed to allow you to easily integrate a monitoring system with a Service 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 API is based around accepting events. Incoming events (sent via the API) 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](doc:become-a-pagerduty-partner). [block:api-header] { "type": "basic", "title": "Getting Started" } [/block] The Events API can be used with any "Generic API" integration in PagerDuty. If you don't already have a "Generic API" integration, you [should create one](https://support.pagerduty.com/hc/en-us/articles/202830340-Creating-a-Generic-API-Service): For creating a new Service with a "Generic API" integration: 1. In your account, under the Services tab, click "Add New Service". 2. Select "Use our API Directly" from the Integration Type menu and enter in an Integration Name. 2. Enter a name for the service and select an escalation policy. 3. Click the "Add Service" button. 4. Once the service is created, you'll be taken to the Integrations tab for that service. On this page, you'll see the "Integration key", which is referred to as "service_key" in our API documentation, and is needed to access the API. [block:api-header] { "type": "basic", "title": "Making a Request" } [/block] To make an API request, POST a JSON body representing the event to ``` https://events.pagerduty.com/generic/2010-04-15/create_event.json ``` 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": "info", "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." } [/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 `integration_key` as the original `trigger` event. Subsequent `acknowledge` or `resolve` events sent via a different `integration_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).