Stay Informed with PagerDuty Webhook Subscriptions

PagerDuty webhooks are evolving.

With the recent introduction of v3 webhook subscriptions, v1 and v2 of PagerDuty webhooks will both be retired in the coming months (v1 EOL Oct. 2022 and v2 EOL March 2023). For those reasons alone, you'll want to update your code to use v3 webhook subscriptions as soon as possible. But, let's also talk about what you'll be gaining by adopting v3 webhook subscriptions.

Webhooks at PagerDuty

The first version of webhooks at PagerDuty covered a relatively small number of events. You essentially could only be notified when an incident was triggered, acknowledged, resolved, assigned, escalated, or delegated.

An incremental update to webhooks came in the form of a v2 release which allowed you to receive webhooks whenever an incident was annotated. However, as the functionality of incidents in PagerDuty increased, so has the need to receive notifications on more than just the core incident events. Things like when an incident has been reassigned, reopened, or the status update on an incident has been published were events that needed webhooks. In addition to the new incident actions, webhooks needed to be able to support other resources in PagerDuty. Resources like Services. V3 webhooks now support when a service is created, updated, or deleted.

The following table shows all the the events supported by webhooks and which version the events are supported in. The data for this table comes from the version comparison section of the PagerDuty documentation on webhooks.

You'll notice a few of the original incident event types have two names, such as trigger and triggered. That's because the names of those events changed in v3 of webhooks. If there is a / in the table above the second name is the v3 version of the event name.

V3 Webhook Subscriptions

V3 webhook subscriptions can be created through the PagerDuty UI and by making calls to the API. For this article we're going to focus on managing subscriptions through the API. For information on managing subscriptions through the UI checkout the Webhooks support documentation.

Create Webhook Subscription Through API

You create a webhook subscription by making a call to the webhook_subscriptions endpoint with a webhook_subscription object defined in the body of the request. The subscription object has three main components--delivery method, events, and filter.

Delivery Method

The delivery_method of a webhook subscription defines how and where a message for an event will be delivered. There are two required fields: type and url. At this time the only valid value for type is http_delivery_method, and the url is the location of where the webhook should be sent.

Events

The events field is an array of event types the webhook subscription is interested in. For a complete list of possible event times, and the syntax for including them, see the Event Types section of the PagerDuty Webhook developer documentation.

Filter

The filter value sets the scope of the events that are being sent. You can filter on three types--service_reference,team_reference, and account_reference.

Putting all of those pieces together, creating a webhook_subscription with a service_reference filter would something like this:

{
  "webhook_subscription": {
    "delivery_method": {
      "type": "email",
      "url": "https://example.com/receive_a_pagerduty_webhook"
    },
    "description": "Sends webhook events somewhere interesting.",
    "events": [
      "incident.acknowledged",
      "incident.annotated",
      "incident.delegated",
      "incident.escalated",
      "incident.priority_updated",
      "incident.reassigned",
      "incident.reopened",
      "incident.resolved",
      "incident.responder.added",
      "incident.responder.replied",
      "incident.unacknowledged",
      "incident.status_update_published"

    ],
    "filter": {
      "id": "PJHZQ7R",
      "type": "service_reference"
    },
    "type": "webhook_subscription"
  }
}

NOTE: Something to be careful of, as of this writing, there isn't a check to see if the service ID you're passing is valid. Make sure to verify your service ID is correct before creating a webhook_subscription.

Webhook Payload

With the webhook subscription created it’s now ready to send webhooks on the subscribed events. The webhook payload for that event looks something like this:

{
  "event": {
    "id": "01D5RHYA931SGC5NALZ1HVKVE2",
    "event_type": "incident.priority_updated",
    "resource_type": "incident",
    "occurred_at": "2022-09-01T23:29:50.459Z",
    "agent": {
      "html_url": "https://pdt-stmcallister.pagerduty.com/users/P5JEPDQ",
      "id": "P5JEPDQ",
      "self": "https://api.pagerduty.com/users/P5JEPDQ",
      "summary": "Scott McAllister",
      "type": "user_reference"
    },
    "client": null,
    "data": {
      "id": "Q39FWCH8OEH7I0",
      "type": "incident",
      "self": "https://api.pagerduty.com/incidents/Q39FWCH8OEH7I0",
      "html_url": "https://pdt-stmcallister.pagerduty.com/incidents/Q39FWCH8OEH7I0",
      "number": 10,
      "status": "acknowledged",
      "incident_key": "59124bec832148a7b9dc5e8c43e1cf7b",
      "created_at": "2022-06-10T19:27:35Z",
      "title": "Something's Broken!",
      "service": {
        "html_url": "https://pdt-stmcallister.pagerduty.com/services/P0IQNQT",
        "id": "P0IQNQT",
        "self": "https://api.pagerduty.com/services/P0IQNQT",
        "summary": "Changie",
        "type": "service_reference"
      },
      "assignees": [
        {
          "html_url": "https://pdt-stmcallister.pagerduty.com/users/P5JEPDQ",
          "id": "P5JEPDQ",
          "self": "https://api.pagerduty.com/users/P5JEPDQ",
          "summary": "Scott McAllister",
          "type": "user_reference"
        }
      ],
      "escalation_policy": {
        "html_url": "https://pdt-stmcallister.pagerduty.com/escalation_policies/P1CSJJO",
        "id": "P1CSJJO",
        "self": "https://api.pagerduty.com/escalation_policies/P1CSJJO",
        "summary": "Default",
        "type": "escalation_policy_reference"
      },
      "teams": [],
      "priority": {
        "html_url": "https://pdt-stmcallister.pagerduty.com/account/incident_priorities",
        "id": "PDNVXWA",
        "self": "https://api.pagerduty.com/priorities/PDNVXWA",
        "summary": "P3",
        "type": "priority_reference"
      },
      "urgency": "high",
      "conference_bridge": null,
      "resolve_reason": null
    }
  }
}

As you can see, there’s a lot to that event object. Something to notice is the event.data object. This is the meat of the incident. It’s where you’ll find information like title and status, as well as the service, assignees, and escalation policy objects. Rather than go into detail about the structure of this payload here in this post, I invite you to head over to the Webhook Payload section of the Webhooks Developer documentation.

Let Us Know

We'd love to hear about your experience migrating to v3 Webhook Subscriptions. Let us know in the comments how things went, or if you have any questions during your migration process.