Webhooks

Webhooks allow you to receive HTTP callbacks when incidents are created, updated and deleted. Details about the event are sent to your specified URL, such as Slack or your own custom PagerDuty webhook processor.

V3 Webhook Subscriptions versus V1/V2 Webhook Extensions

Conceptually, V3 webhook subscriptions and V1/V2 generic webhook extensions are similar; however, there are some differences:

  • V3 Webhook Subscription: A subscription configured to send a webhook to an endpoint every time an event happens on an incident and within a specific scope (team or service) that you care about.
  • V1/V2 Generic Webhook Extension: An endpoint configured to be sent webhooks every time an incident is created, updated, or deleted.

Key Differences

Payload

The final payload of the webhook differs between V1/V2 and V3. The destination service of the webhook will need to be tweaked to handle the new payload.

Custom Headers

Currently, V3 webhook subscriptions do not support the custom headers that are available in V2 webhooks, however this capability is in development.

Response Headers

The user-agent header in the request displays which webhooks version was used: PagerDuty-Webhook/V2.0 for V2 and PagerDuty-Webhook/V3.0 for V3.

V3 webhook subscriptions also introduce two new headers: x-webhook-subscription and x-pagerduty-signature.

Add a V3 Webhook Subscription

πŸ“˜

Note

If you are currently using V1/V2 webhook extensions and would like to migrate them to V3 webhook subscriptions, please follow our migration guide below.

  1. Navigate to Integrations Generic Webhooks V3. Click Add Webhook in the Overview tab.
  2. You will then be directed to the Mapping tab. Enter the Webhook URL, under Scope Type select Service or Team based on your preferences, under Scope select the desired service or team, and then enter a Description. Under Events to Send, select either Send all events or Send selected events. If you select Send selected events, you will then be prompted to check the event types you would like sent.
  3. Click Add Webhook.

Supported Resources and Event Types

The following resources and event types are available with V3 webhooks. Additional event types may be added to this list over time.

Incidents:

Event Type

Description

acknowledged

sent when an incident is acknowledged

annotated

sent when a note is added to an incident

delegated

sent when an incident has been reassigned to another escalation policy

escalated

sent when an incident has been escalated to another user in the same escalation level

reassigned

sent when an incident has been reassigned to another user

reopened

sent when an incident is reopened

resolved

sent when an incident has been resolved

status_update_published

sent when a status update is added to an incident

triggered

sent when an incident is newly created/triggered

unacknowledged

sent when an incident is unacknowledged

responder.added

sent when a responder has been added to an incident

responder.replied

sent when a responder replies to a request

priority_updated

sent when the priority of an incident has changed

Services:

Event Type

Description

updated

sent when a service is updated

created

sent when a service is created

deleted

sent when a service is deleted

Add a Webhook Extension

❗️

Deprecation

V1 webhook extensions will be deprecated by November 17, 2021 and V2 by March 31, 2022.

  1. Navigate to Services Service Directory, then click the name of the service you want to add a webhook to.
  2. Select the Integrations tab, under Extensions and Add-Ons, click Add or manage extensions for this service and then click New Extension.
  3. For the Extension Type select your webhook type or Generic V2 Webhook.
  4. Enter a Name for your webhook.
  5. Enter your endpoint's URL in the Details field.
  6. Click Save.

To test your webhook, click New Incident on the service to trigger a test incident, and then check your endpoint for updates. We recommend reviewing the webhook PagerDuty sends when an incident triggers. You can do this by using a tool online such as Beeceptor, webhook.site, or postb.in.

Custom Headers

πŸ“˜

Note

Custom headers are currently only supported with V1/V2 generic webhook extensions.

Custom headers can be added to outgoing webhook requests, allowing you to input pairs of header names and header values. Up to five custom headers can be added to each webhook. For security purposes, the header values will not be visible and cannot be edited once saved.

  1. Navigate to Integrations Extensions, then click the icon next to the webhook extension you want to custom headers to, click Edit.
  2. Click + Add Custom Header.
  3. Enter the custom header name and header value.
  4. Click Save.

Migrating from V1/V2 Generic Extensions to V3 Webhook Subscriptions

The following guide explains how to migrate existing V1/V2 generic webhook extensions to V3 webhook subscriptions.

πŸ“˜

API Token

An API token will have to be generated on the account before making these API calls.

Step 1: Get a List of Existing Webhooks

Get a list of the existing V2 webhooks using the extensions API endpoint. It may be helpful to set the query field in the request to webhook to filter by Generic Webhooks only.

In this example, when the GET /extensions endpoint is called, the response contains a list containing a single extension:

{
    "extensions": [
        {
            "endpoint_url": "https://example.com/webhooks_go_here",
            "name": "My Webhook",
            "config": {
                "headers": null,
                "referer": "https://subdomain.pagerduty.com/extensions"
            },
            "extension_schema": {
                "id": "PJFWPEP",
                "type": "extension_schema_reference",
                "summary": "Generic V2 Webhook",
                "self": "https://api.pagerduty.com/extension_schemas/PJFWPEP",
                "html_url": null
            },
            "extension_objects": [
                {
                    "id": "PYKHOXQ",
                    "type": "service_reference",
                    "summary": "My Application Service",
                    "self": "https://api.pagerduty.com/services/PYKHOXQ",
                    "html_url": "https://subdomain.pagerduty.com/service-directory/PYKHOXQ"
                }
            ],
            "id": "PUGLEKG",
            "type": "webhook",
            "summary": "My Webhook",
            "self": "https://api.pd-staging.com/webhooks/PUGLEKG",
            "html_url": null
        }
    ],
    "query": "webhook",
    "limit": 25,
    "offset": 0,
    "total": null,
    "more": false
}

Step 2: Note the Important Fields

In the response of GET /extensions, for each extension in the extensions array, take note of the endpoint_url, name, and id. To get the service that the extension is linked with, take the id and type inside the extension_objects array.

From the response in Step 1, take note of lines 4, 5, 19, 20, and 26.

Step 3: Decide on Event Types

V3 webhook subscriptions introduce a new way to refine subscriptions with events types. Before creating a new V3 webhook subscription, event types will need to be selected.

πŸ“˜

Note

In order to receive the same data as a V2 generic webhook extension, all V3 event types will need to be added.

To replicate the existing behavior of the V2 generic webhook extension, all of the available event_types will be used:

"incident.acknowledged"
"incident.annotated"
"incident.delegated"
"incident.escalated"
"incident.priority_updated"
"incident.reassigned"
"incident.reopened"
"incident.resolved"
"incident.responder.added"
"incident.responder.replied"
"incident.triggered"
"incident.unacknowledged"

Step 4: Create a New V3 Webhook Subscription

Using the webhooks subscriptions API endpoint, a webhook subscription can now be created. A mapping of the old V2 request to the new V3 request is described below.

V2 Generic Webhook Extension

V3 Webhook Subscription

endpoint_url

delivery_method.url

name

description

extension_objects.id

filter.id

extension_objects.type

filter.type

The new request to POST /webhook_subscriptions will look like the following:

{
    "webhook_subscription": {
        "delivery_method": {
            "type": "http_delivery_method",
            "url": "https://example.com/webhooks_go_here"
        },
        "description": "My Webhook"
        "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.triggered",
            "incident.unacknowledged"
        ],
        "filter": {
            "id": "PYKHOXQ",
            "type": "service_reference"
        },
        "type": "webhook_subscription"
    }
}

Step 5: Cleanup

At this point, a new V3 webhook subscription has been created that will replicate the existing V2 generic webhook extension. Duplicate webhooks will be sent so long as both V2 and V3 subscriptions exist. Once it is confirmed that the new V3 webhook subscription is functional, the old V2 generic webhook extension should be deleted using the id found in Step 1.

In the example, the old extension id is found on line 26 from Step 1.

Updated 26 days ago


Learn more

You can read more about PagerDuty Webhooks in our Developer Docs here:

Webhook Behavior

Webhooks


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.