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.

• An explanation of a V3 payload is shown here.
• An explanation of a V2 payload is shown here.

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 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.

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.

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.