{"_id":"58aefd255bedb31900382f65","category":{"_id":"58aefce02470660f00b54539","version":"564e5a9b1560880d008d30dc","project":"564e5930c3553e0d003e53d0","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2017-02-23T15:16:48.589Z","from_sync":false,"order":3,"slug":"events-api-v2","title":"Events API v2"},"__v":0,"project":"564e5930c3553e0d003e53d0","githubsync":"","user":"5876ca441a6b5b3900a5b348","version":{"_id":"564e5a9b1560880d008d30dc","project":"564e5930c3553e0d003e53d0","__v":22,"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"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"Foundation","version_clean":"2.0.0","version":"2"},"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-02-23T15:17:57.226Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"The Events API (v2)  enables you to add PagerDuty's advanced event and incident management functionality to any system that can make an HTTP API call.\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Description\"\n}\n[/block]\nThe Events API v2 is designed to allow you to easily integrate a monitoring system with PagerDuty. Monitoring systems generally send out events when problems are detected and when these problems have been resolved (fixed). Certain systems also understand the concept of acknowledgements: problems can be acknowledged by a person to signal that they are working on fixing the issue.\n\nThe Events API v2 is a highly reliable, highly available asynchronous API that ingests events from monitoring tools. Events sent via this API are routed to a PagerDuty service and processed. They may result in a new alert and/or incident being created, or an existing one being updated or resolved.\n\nPreviously, the Events API was also used to integrate PagerDuty with ticketing systems and various other software tools. As of 2017, we now recommend using our new synchronous [Incidents API](https://v2.developer.pagerduty.com/v2/page/api-reference#!/Incidents/post_incidents) to integrate ticketing systems or other systems of record. \n\nIf you are using a custom monitoring tool, library, or script that has not yet been updated to v2, you should use the [Events API v1](https://v2.developer.pagerduty.com/docs/events-api) instead. \n\nInterested in becoming a PagerDuty partner? Fill out [this form](https://pdconnect.wufoo.com/forms/become-a-pagerduty-partner/) for more information.\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Getting Started\"\n}\n[/block]\nTo use the Events API v2, you need to set up an appropriate integration endpoint in PagerDuty. If you do not already have an integration, you can create one from any PagerDuty service. When creating the integration, select “Events API v2” for “Integration Type.”\n\nYou will need to include the integration key for your new integration, as a routing_key in the event payload.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Making a request\"\n}\n[/block]\nTo make an API request, POST a JSON object (size limited to **512 KB**) of the desired event type to the following URL:\n```\nhttps://events.pagerduty.com/v2/enqueue\n```\n\nYour request should specify an event action (see below), a routing key generated from the PD integration, and values for *summary*, *severity*, and *source*.\n\nHead on over to [Send an Event](https://v2.developer.pagerduty.com/v2/docs/send-an-event-events-api-v2) to see the full details of the event body format and to send an event to PagerDuty right from the documentation.\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Event Action\"\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 Action\",\n    \"h-1\": \"Description\",\n    \"0-1\": \"When PagerDuty receives a trigger event, it will either open a new alert, or add a new trigger log entry to an existing alert, depending on the provided dedup_key. Your monitoring tools should send PagerDuty a trigger when a new problem has been detected. You *may* send additional triggers when a previously detected problem has occurred again.\",\n    \"0-0\": \"`trigger`\",\n    \"1-0\": \"`acknowledge`\",\n    \"1-1\": \"`acknowledge` events cause the referenced incident to enter the acknowledged state.\\nWhile an incident is acknowledged, it won't generate any additional notifications, even if it receives new trigger events.\\nYour monitoring tools should send PagerDuty an acknowledge event when they know someone is presently working on the problem\",\n    \"2-0\": \"`resolve`\",\n    \"2-1\": \"`resolve` events cause the referenced incident to enter the resolved state.\\nOnce an incident is resolved, it won't generate any additional notifications. New trigger events with the same dedup_key as a resolved incident won't re-open the incident. Instead, a new incident will be created.\\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  \"title\": \"PagerDuty Common Event Format (PD-CEF)\"\n}\n[/block]\nThe Events API v2 accepts data in the [PagerDuty Common Event Format](https://support.pagerduty.com/docs/pd-cef), a new schema for operations data released by PagerDuty in 2016. PD-CEF helps PagerDuty provide a more useful and consistent experience for our customers across all their different monitoring systems. Across different integrations, event types, services, and teams, users can see and use data to rapidly assess emerging situations, customize event, alert, and incident workflow, and optimize their operational processes.\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"Summary\",\n    \"h-0\": \"Field\",\n    \"h-1\": \"Description\",\n    \"h-2\": \"Type\",\n    \"h-3\": \"Required?\",\n    \"h-4\": \"Examples\",\n    \"0-1\": \"A high-level, text summary message of the event. Will be used to construct an alert's description.\",\n    \"0-2\": \"String\",\n    \"0-3\": \"Required\",\n    \"0-4\": \"\\\"PING OK - Packet loss = 0%, RTA = 1.41 ms\\\"w\\n\\\"Host 'acme-andromeda-sv1-c40 :: 179.21.24.50' is DOWN\\\"\",\n    \"1-0\": \"Severity\",\n    \"1-1\": \"How impacted the affected system is. Displayed to users in lists and influences the priority of any created incidents.\",\n    \"1-2\": \"Enum\",\n    \"1-3\": \"Required\",\n    \"1-4\": \"Enum {Info, Warning, Error, Critical}\",\n    \"2-0\": \"Source\",\n    \"2-1\": \"Specific human-readable unique identifier, such as a hostname, for the system having the problem.\",\n    \"2-2\": \"String\",\n    \"2-3\": \"Required\",\n    \"2-4\": \"\\\"prod05.theseus.acme-widgets.com\\\"\\n\\\"171.26.23.22\\\"\\n\\\"aws:elasticache:us-east-1:852511987:cluster/api-stats-prod-003\\\"\\n\\\"9c09acd49a25\\\"\",\n    \"3-0\": \"Timestamp\",\n    \"3-1\": \"When the upstream system detected / created the event. This is useful if a system batches or holds events before sending them to PagerDuty.\",\n    \"3-2\": \"Timestamp (ISO 8601)\",\n    \"3-3\": \"Optional - Will be auto-generated by PagerDuty if not provided.\",\n    \"3-4\": \"2015-07-17T08:42:58.315+0000\",\n    \"4-0\": \"Component\",\n    \"4-1\": \"The part or component of the affected system that is broken.\",\n    \"4-2\": \"String\",\n    \"4-3\": \"Optional\",\n    \"4-4\": \"\\\"keepalive\\\"\\n\\\"webping\\\"\\n\\\"mysql\\\"\\n\\\"wqueue\\\"\",\n    \"5-0\": \"Group\",\n    \"5-1\": \"A cluster or grouping of sources. For example, sources “prod-datapipe-02” and “prod-datapipe-03” might both be part of “prod-datapipe”\",\n    \"5-2\": \"String\",\n    \"5-3\": \"Optional\",\n    \"5-4\": \"\\\"prod-datapipe\\\"\\n\\\"www\\\"\\n\\\"web_stack\\\"\",\n    \"6-0\": \"Class\",\n    \"6-1\": \"The class/type of the event\",\n    \"6-2\": \"String\",\n    \"6-3\": \"Optional\",\n    \"6-4\": \"\\\"High CPU\\\"\\n\\\"Latency\\\"\\n\\\"500 Error\\\"\",\n    \"7-0\": \"Custom Details\",\n    \"7-1\": \"Free-form details from the event\",\n    \"7-2\": \"Object\",\n    \"7-3\": \"Optional\",\n    \"7-4\": \"{\\\"ping time\\\": \\\"1500ms\\\", \\\"load avg\\\": 0.75 }\"\n  },\n  \"cols\": 5,\n  \"rows\": 8\n}\n[/block]\nFor more information about PD-CEF and how it is used in PagerDuty, please see [this knowledge base article](https://support.pagerduty.com/docs/pd-cef). \n\nAs a PagerDuty monitoring partner, adapting the new PD-CEF format provides your customers with a more streamlined and useful user experience within PagerDuty. Customers can see the most important details about an event front-and-center during initial triage, enabling them to rapidly determine whether a problem needs further investigation within the monitoring system, or whether action can immediately be taken. If you are a monitoring partner and interested in converting your integration to PD-CEF, please email us at partners:::at:::pagerduty.com.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Alert De-Duplication\"\n}\n[/block]\nEvery event has a `dedup_key`: a string which identifies the alert triggered for the given event. The `dedup_key` can be specified when submitting the first trigger event that creates an alert. If omitted, it will be generated automatically by PagerDuty and returned in the Events API v2 response.\n\nSubmitting subsequent events for the same `dedup_key` will result in those events being applied to an open alert matching that dedup_key. Once the alert is resolved, any further events with the same `dedup_key` will create a new alert (for trigger events) or be dropped (for `acknowledge` and `resolve` events).\n\nSubsequent events for the same `dedup_key` will only apply to the open alert if the events are sent via the same `routing_key` as the original trigger event. Subsequent acknowledge or resolve events sent via a different `routing_key` from the original will be dropped. \n\nIf a trigger event is sent without `dedup_key`, it will always generate a new alert because the key is a [UUID](https://v2.developer.pagerduty.com/v2/docs/types#uuid).\n\nAlerts can be further grouped into Incidents, for centralizing incident response and context. For more on the way events, alerts, and incidents interact, please see [this knowledge base article](https://support.pagerduty.com/docs/alerts).\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"API Response Codes & Retry Logic\"\n}\n[/block]\n  Ideally, the API request will succeed and the PagerDuty server will indicate that it successfully received that event. In practice, the request may fail due to various reasons.\n\n  The following table shows the possible results of the API request and if you need to retry the API call for that result:\n\n\n  | Result  | Description   | Retry? |\n  | ------- | ------------- | ------ |\n  | 202     | Accepted - The event has been accepted by PagerDuty.  | No |\n  | 400     | Bad Request - Check that the JSON is valid.     | No |\n  | 429     | Too many API calls at a time.                             | Yes - retry after some time. |\n  | 500 or other 5XX  | Internal Server Error - the PagerDuty server experienced an error while processing the event. | Yes - retry after some time. |\n  | Networking Error  | Error while trying to communicate with PagerDuty servers.   | Yes - retry after some time. |\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"API Limits\"\n}\n[/block]\nThere is a limit on the number of events that a service can accept at any given time. Depending on the behaviour of the incoming traffic and how many incidents are being created at once, we dynamically adjust our throttle limits.\n\n If each of the events your monitoring system is sending is important, be sure to retry on a 429 response code, preferably with a backoff of a few minutes.","excerpt":"Using the Events API V2 to send events to PagerDuty","slug":"events-api-v2","type":"basic","title":"Overview"}

Overview

Using the Events API V2 to send events to PagerDuty

The Events API (v2) enables you to add PagerDuty's advanced event and incident management functionality to any system that can make an HTTP API call. [block:api-header] { "type": "basic", "title": "Description" } [/block] The Events API v2 is designed to allow you to easily integrate a monitoring system with PagerDuty. Monitoring systems generally send out events when problems are detected and when these problems have been resolved (fixed). Certain systems also understand the concept of acknowledgements: problems can be acknowledged by a person to signal that they are working on fixing the issue. The Events API v2 is a highly reliable, highly available asynchronous API that ingests events from monitoring tools. Events sent via this API are routed to a PagerDuty service and processed. They may result in a new alert and/or incident being created, or an existing one being updated or resolved. Previously, the Events API was also used to integrate PagerDuty with ticketing systems and various other software tools. As of 2017, we now recommend using our new synchronous [Incidents API](https://v2.developer.pagerduty.com/v2/page/api-reference#!/Incidents/post_incidents) to integrate ticketing systems or other systems of record. If you are using a custom monitoring tool, library, or script that has not yet been updated to v2, you should use the [Events API v1](https://v2.developer.pagerduty.com/docs/events-api) instead. Interested in becoming a PagerDuty partner? Fill out [this form](https://pdconnect.wufoo.com/forms/become-a-pagerduty-partner/) for more information. [block:api-header] { "type": "basic", "title": "Getting Started" } [/block] To use the Events API v2, you need to set up an appropriate integration endpoint in PagerDuty. If you do not already have an integration, you can create one from any PagerDuty service. When creating the integration, select “Events API v2” for “Integration Type.” You will need to include the integration key for your new integration, as a routing_key in the event payload. [block:api-header] { "type": "basic", "title": "Making a request" } [/block] To make an API request, POST a JSON object (size limited to **512 KB**) of the desired event type to the following URL: ``` https://events.pagerduty.com/v2/enqueue ``` Your request should specify an event action (see below), a routing key generated from the PD integration, and values for *summary*, *severity*, and *source*. Head on over to [Send an Event](https://v2.developer.pagerduty.com/v2/docs/send-an-event-events-api-v2) to see the full details of the event body format and to send an event to PagerDuty right from the documentation. [block:api-header] { "type": "basic", "title": "Event Action" } [/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 Action", "h-1": "Description", "0-1": "When PagerDuty receives a trigger event, it will either open a new alert, or add a new trigger log entry to an existing alert, depending on the provided dedup_key. Your monitoring tools should send PagerDuty a trigger when a new problem has been detected. You *may* send additional triggers when a previously detected problem has occurred again.", "0-0": "`trigger`", "1-0": "`acknowledge`", "1-1": "`acknowledge` events cause the referenced incident to enter the acknowledged state.\nWhile an incident is acknowledged, it won't generate any additional notifications, even if it receives new trigger events.\nYour monitoring tools should send PagerDuty an acknowledge event when they know someone is presently working on the problem", "2-0": "`resolve`", "2-1": "`resolve` events cause the referenced incident to enter the resolved state.\nOnce an incident is resolved, it won't generate any additional notifications. New trigger events with the same dedup_key as a resolved incident won't re-open the incident. Instead, a new incident will be created.\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] { "title": "PagerDuty Common Event Format (PD-CEF)" } [/block] The Events API v2 accepts data in the [PagerDuty Common Event Format](https://support.pagerduty.com/docs/pd-cef), a new schema for operations data released by PagerDuty in 2016. PD-CEF helps PagerDuty provide a more useful and consistent experience for our customers across all their different monitoring systems. Across different integrations, event types, services, and teams, users can see and use data to rapidly assess emerging situations, customize event, alert, and incident workflow, and optimize their operational processes. [block:parameters] { "data": { "0-0": "Summary", "h-0": "Field", "h-1": "Description", "h-2": "Type", "h-3": "Required?", "h-4": "Examples", "0-1": "A high-level, text summary message of the event. Will be used to construct an alert's description.", "0-2": "String", "0-3": "Required", "0-4": "\"PING OK - Packet loss = 0%, RTA = 1.41 ms\"w\n\"Host 'acme-andromeda-sv1-c40 :: 179.21.24.50' is DOWN\"", "1-0": "Severity", "1-1": "How impacted the affected system is. Displayed to users in lists and influences the priority of any created incidents.", "1-2": "Enum", "1-3": "Required", "1-4": "Enum {Info, Warning, Error, Critical}", "2-0": "Source", "2-1": "Specific human-readable unique identifier, such as a hostname, for the system having the problem.", "2-2": "String", "2-3": "Required", "2-4": "\"prod05.theseus.acme-widgets.com\"\n\"171.26.23.22\"\n\"aws:elasticache:us-east-1:852511987:cluster/api-stats-prod-003\"\n\"9c09acd49a25\"", "3-0": "Timestamp", "3-1": "When the upstream system detected / created the event. This is useful if a system batches or holds events before sending them to PagerDuty.", "3-2": "Timestamp (ISO 8601)", "3-3": "Optional - Will be auto-generated by PagerDuty if not provided.", "3-4": "2015-07-17T08:42:58.315+0000", "4-0": "Component", "4-1": "The part or component of the affected system that is broken.", "4-2": "String", "4-3": "Optional", "4-4": "\"keepalive\"\n\"webping\"\n\"mysql\"\n\"wqueue\"", "5-0": "Group", "5-1": "A cluster or grouping of sources. For example, sources “prod-datapipe-02” and “prod-datapipe-03” might both be part of “prod-datapipe”", "5-2": "String", "5-3": "Optional", "5-4": "\"prod-datapipe\"\n\"www\"\n\"web_stack\"", "6-0": "Class", "6-1": "The class/type of the event", "6-2": "String", "6-3": "Optional", "6-4": "\"High CPU\"\n\"Latency\"\n\"500 Error\"", "7-0": "Custom Details", "7-1": "Free-form details from the event", "7-2": "Object", "7-3": "Optional", "7-4": "{\"ping time\": \"1500ms\", \"load avg\": 0.75 }" }, "cols": 5, "rows": 8 } [/block] For more information about PD-CEF and how it is used in PagerDuty, please see [this knowledge base article](https://support.pagerduty.com/docs/pd-cef). As a PagerDuty monitoring partner, adapting the new PD-CEF format provides your customers with a more streamlined and useful user experience within PagerDuty. Customers can see the most important details about an event front-and-center during initial triage, enabling them to rapidly determine whether a problem needs further investigation within the monitoring system, or whether action can immediately be taken. If you are a monitoring partner and interested in converting your integration to PD-CEF, please email us at partners@pagerduty.com. [block:api-header] { "type": "basic", "title": "Alert De-Duplication" } [/block] Every event has a `dedup_key`: a string which identifies the alert triggered for the given event. The `dedup_key` can be specified when submitting the first trigger event that creates an alert. If omitted, it will be generated automatically by PagerDuty and returned in the Events API v2 response. Submitting subsequent events for the same `dedup_key` will result in those events being applied to an open alert matching that dedup_key. Once the alert is resolved, any further events with the same `dedup_key` will create a new alert (for trigger events) or be dropped (for `acknowledge` and `resolve` events). Subsequent events for the same `dedup_key` will only apply to the open alert if the events are sent via the same `routing_key` as the original trigger event. Subsequent acknowledge or resolve events sent via a different `routing_key` from the original will be dropped. If a trigger event is sent without `dedup_key`, it will always generate a new alert because the key is a [UUID](https://v2.developer.pagerduty.com/v2/docs/types#uuid). Alerts can be further grouped into Incidents, for centralizing incident response and context. For more on the way events, alerts, and incidents interact, please see [this knowledge base article](https://support.pagerduty.com/docs/alerts). [block:api-header] { "type": "basic", "title": "API Response Codes & Retry Logic" } [/block] Ideally, the API request will succeed and the PagerDuty server will indicate that it successfully received that event. In practice, the request may fail due to various reasons. The following table shows the possible results of the API request and if you need to retry the API call for that result: | Result | Description | Retry? | | ------- | ------------- | ------ | | 202 | Accepted - The event has been accepted by PagerDuty. | No | | 400 | Bad Request - Check that the JSON is valid. | No | | 429 | Too many API calls at a time. | Yes - retry after some time. | | 500 or other 5XX | Internal Server Error - the PagerDuty server experienced an error while processing the event. | Yes - retry after some time. | | Networking Error | Error while trying to communicate with PagerDuty servers. | Yes - retry after some time. | [block:api-header] { "type": "basic", "title": "API Limits" } [/block] There is a limit on the number of events that a service can accept at any given time. Depending on the behaviour of the incoming traffic and how many incidents are being created at once, we dynamically adjust our throttle limits. If each of the events your monitoring system is sending is important, be sure to retry on a 429 response code, preferably with a backoff of a few minutes.