Webhooks API

Webhooks let you recieve HTTP callbacks when interesting events happen within your PagerDuty account. Details surrounding the interesting event will be sent via HTTP to a URL that you specify.

PagerDuty currently supports incident-based webhooks. After adding a webhook URL to a PagerDuty service, the triggering of new incidents on that service will cause outgoing webhook messages to be sent to that URL. In addition, certain interesting changes to an incident's state will cause other types of incident webhook messages to be sent: Generally, any change to the status or assigned_to_user of an incident will cause an outgoing message to be sent.

The following incident webhook message types are supported:

TypeDescription
incident.triggerSent when an incident is newly created/triggered.
incident.acknowledgeSent when an incident has had its status changed from triggered to acknowledged.
incident.unacknowledgeSent when an incident is unacknowledged due to timeout.
incident.resolveSent when an incident has been resolved.
incident.assignSent when an incident has been manually reassigned to another user in a different escalation chain.
incident.escalateSent when an incident has been escalated to another user in the same escalation chain.
incident.delegateSent when an incident has been reassigned to another escalation chain.

NOTE: As new types of incident actions are supported, new incident webhook message types will be added.

Parameters

NameTypeRequiredDescription
idIntegerYesUniquely identifies this outgoing webhook message; can be used for idempotency when processing the messages.
typeStringYesThe webhook message type (see above list).
created_onDateYesThe date/time when the incident changed state.
dataStringYesThe incident details at the time of the state change. Incident details are formatted similarly to the results of the Incident API.

NOTE: Outgoing messages are sent in an array. It is possible that multiple outgoing messages will be batched together and sent all at once from PagerDuty in a single outgoing webhook.

Sample Outbound Webhook Incident Payload (both a trigger and a resolve at once)

{
  "messages": [
    {
      "id": "bb8b8fe0-e8d5-11e2-9c1e-22000afd16cf",
      "created_on": "2013-07-09T20:25:44Z",
      "type": "incident.trigger",
      "data": {
        "incident": {
          "id": "PIJ90N7",
          "incident_number": 1,
          "created_on": "2013-07-09T20:25:44Z",
          "status": "triggered",
          "html_url": "https://acme.pagerduty.com/incidents/PIJ90N7",
          "incident_key": "null",
          "service": {
            "id": "PBAZLIU",
            "name": "service",
            "html_url": "https://acme.pagerduty.com/services/PBAZLIU"
          },
          "assigned_to_user": {
            "id": "PPI9KUT",
            "name": "Alan Kay",
            "email": "alan@pagerduty.com",
            "html_url": "https://acme.pagerduty.com/users/PPI9KUT"
          },
          "trigger_summary_data": {
            "subject": "45645"
          },
          "trigger_details_html_url": "https://acme.pagerduty.com/incidents/PIJ90N7/log_entries/PIJ90N7",
          "last_status_change_on": "2013-07-09T20:25:44Z",
          "last_status_change_by": "null"
        }
      }
    },
    {
      "id": "8a1d6420-e9c4-11e2-b33e-f23c91699516",
      "created_on": "2013-07-09T20:25:45Z",
      "type": "incident.resolve",
      "data": {
        "incident": {
          "id": "PIJ90N7",
          "incident_number": 1,
          "created_on": "2013-07-09T20:25:44Z",
          "status": "resolved",
          "html_url": "https://acme.pagerduty.com/incidents/PIJ90N7",
          "incident_key": "null",
          "service": {
            "id": "PBAZLIU",
            "name": "service",
            "html_url": "https://acme.pagerduty.com/services/PBAZLIU"
          },
          "assigned_to_user": "null",
          "resolved_by_user": {
            "id": "PPI9KUT",
            "name": "Alan Kay",
            "email": "alan@pagerduty.com",
            "html_url": "https://acme.pagerduty.com/users/PPI9KUT"
          },
          "trigger_summary_data": {
            "subject": "45645"
          },
          "trigger_details_html_url": "https://acme.pagerduty.com/incidents/PIJ90N7/log_entries/PIJ90N7",
          "last_status_change_on": "2013-07-09T20:25:45Z",
          "last_status_change_by": {
            "id": "PPI9KUT",
            "name": "Alan Kay",
            "email": "alan@pagerduty.com",
            "html_url": "https://acme.pagerduty.com/users/PPI9KUT"
          }
        }
      }
    }
  ]
}

Troubleshooting

If you have any issues debugging your webhooks, you can use RequestBin to debug them.