The PagerDuty event integration API is how you would add PagerDuty’s advanced alerting functionality to any system that can make an HTTP API call. You can now add phone, SMS and email alerting to your monitoring tools, ticketing systems and custom software.
The event integration API can be used with any “Generic API” service in PagerDuty. If you don’t already have a “Generic API” service, you should create one:
To make an API request, POST a JSON event object to the following URL:
https://events.pagerduty.com/generic/2010-04-15/create_event.json
Note: You may also use the following non-SSL URL:
http://events.pagerduty.com/generic/2010-04-15/create_event.json
The 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 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.
The events API accepts three types of events: triggers, acknowledges, and resolves.
Your monitoring tools should send PagerDuty a trigger event to report a new or ongoing problem. 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.
This example shows how to make a request with a specific incident_key. Note that if an incident with this key already exists, this trigger message will simply be appended to it. If no incident with this key exists, a new one will be automatically created. When the incident_key is provided in the request, the same value will always be returned in the response.
Request
{
"service_key": "e93facc04764012d7bfb002500d5d1a6",
"incident_key": "srv01/HTTP",
"event_type": "trigger",
"description": "FAILURE for production/HTTP on machine srv01.acme.com",
"details": {
"ping time": "1500ms",
"load avg": 0.75
}
}
Response
{
"status": "success",
"message": "Event processed",
"incident_key": "srv01/HTTP"
}
This example shows how to make a request without an incident_key. In this case, PagerDuty will automatically assign a random and unique key and return it in the response object. You should store this key in case you want to send an acknowledge or resolve event to this incident in the future.
Request
{
"service_key": "e93facc04764012d7bfb002500d5d1a6",
"event_type": "trigger",
"description": "FAILURE for production/HTTP on machine srv01.acme.com",
"details": {
"ping time": "1500ms",
"load avg": 0.75
}
}
Response
{
"status": "success",
"message": "Event processed",
"incident_key": "73af7a305bd7012d7c06002500d5d1a6"
}
Acknowledge events cause the referenced incident to enter the acknowledged state. While an incident is acknowledged, it won’t generate any additional notifications, even if it receives new trigger events. Your monitoring tools should send PagerDuty an acknowledge event when they know someone is presently working on the problem.
Request
{
"service_key": "e93facc04764012d7bfb002500d5d1a6",
"incident_key": "srv01/HTTP",
"event_type": "acknowledge",
"description": "Andrew now working on the problem.",
"details": {
"work started": "2010-06-10 05:43"
}
}
Response
{
"status": "success",
"message": "Event processed",
"incident_key": "srv01/HTTP"
}
Resolve events cause the referenced incident to enter the resolved state. Once 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. Your monitoring tools should send PagerDuty a resolve event when the problem that caused the initial trigger event has been fixed.
Request
{
"service_key": "e93facc04764012d7bfb002500d5d1a6",
"incident_key": "srv01/HTTP",
"event_type": "resolve",
"description": "Andrew fixed the problem.",
"details": {
"fixed at": "2010-06-10 06:00"
}
}
Response
{
"status": "success",
"message": "Event processed",
"incident_key": "srv01/HTTP"
}
If the request is well-formatted, PagerDuty will respond to it with HTTP code 200 and an object with the following fields:
If the request is invalid, PagerDuty will respond with HTTP code 400 and an object with the following fields:
Although unlikely, a response code of 5xx indicates problems on our end. Should this happen, please retry your request after a short delay.
