Webhooks allow you to receive HTTP callbacks when significant events happen in your PagerDuty account, for example, when an incident triggers, escalates or resolves. Details about the event are sent to your specified URL, such as Slack or your own custom PagerDuty webhook processor.

👍

Migrate to V3 Webhook Subscriptions

• If you are currently using V1/V2 webhook extensions and need to migrate them to V3 webhook subscriptions, please follow our migration guide.
• V1 webhook extensions became unsupported on November 13, 2021 and will lose functionality in October, 2022.
• V2 webhooks extensions will become unsupported in October, 2022 and will lose functionality in March, 2023.

Webhook IPs

🚧

Safelist Updates

As of May 5th, 2022 : The /webhook_ips endpoint will no longer be updated, and the page linked below should be used for all safelist updates.

For a list of IP addresses that PagerDuty uses to send webhooks in each of our service regions, visit our Developer Documentation.

Add a V3 Webhook Subscription

🚧

Required User Permissions

• All users, with the exception of Limited Stakeholders, can add V3 Webhook subscriptions.
• Restricted Access Base Role: If you are a user with a Restricted Access base role and Manager team role, then you can create and manage your V3 webhooks by going directly to the V3 webhooks management page at [YOUR-SUBDOMAIN].pagerduty.com/integrations/webhooks.

1. Navigate to Integrations Generic Webhooks (v3).
2. Click New Webhook.
3. Configure your webhook:
   • Enter the Webhook URL.
   • Under Scope Type select Service, Team or Account based on your preferences.
   • Under Scope select the desired service or team.
   • Enter a Description.
   • Under Event Subscription, select which events you want to send a webhook.
4. Click Add Webhook.

Edit a V3 Webhook Subscription

1. Navigate to Integrations Generic Webhooks (v3).
2. Select the webhook’s URL or Manage.
3. Click Edit and make the required changes.
4. Click Save Changes.

Send a Test Event

To test that your webhook is configured correctly and that payloads arrive at the other end:

1. Navigate to Integrations Generic Webhooks (v3).
2. Select the webhook’s URL or Manage.
3. Under Test select Send Test Event.
4. In the confirmation modal, click Yes, Send Event.

Here is an example of the test event’s payload:

{
  "event": {
    "id": "01CH754SM17TWPE2V2H4VPBRO7",
    "event_type": "pagey.ping",
    "resource_type": "pagey",
    "occurred_at": "2021-12-08T22:58:53.510Z",
    "agent": null,
    "client": null,
    "data": {
      "message": "Hello from your friend Pagey!",
      "type": "ping"
    }
  }
}

Delete a V3 Webhook Subscription

1. Navigate to Integrations Generic Webhooks (v3).
2. To the right of the webhook subscription you’d like to delete, select Delete.
3. In the confirmation modal, select Delete.
   • Note: This action cannot be undone.

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

Services

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.

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

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. V1 webhook extensions became unsupported on November 13, 2021 and will lose functionality in October, 2022. V2 webhooks extensions will become unsupported in October, 2022 and will lose functionality in March, 2023.

🚧

Required User Permissions

• Admins or Account Owners can migrate an account’s V1/V2 webhook extensions to V3 webhook subscriptions.
• Team Managers can migrate a subset of an account’s V1/V2 webhook extensions to V3 webhook subscriptions based on their Team access.

Step 1: Generate an API Key

Admins and Account Owners:

1. Generate an API key by navigating to Integrations API Access Keys Create New API Key.
2. Enter a Description that will help you identify the key later on. If you would like it to be read-only, check the Read-only option. Click Create Key.
3. A unique API key will be generated. Copy it to a safe place, as you will not have access to copy this key again. Once it has been copied, click Close. If you lose a key you will need to delete it and create a new one.

Team Managers:

🚧

Restrictions

• Please note that Team Managers will only be able to migrate webhooks for the Teams they are assigned to. They will not be able to migrate an entire account's webhooks.
• If you want to migrate webhooks for an entire account, please have an Admin or Account Owner perform the instructions above.

1. Generate a user API key by navigating to User Icon My Profile User Settings tab Create API User Token.
2. Enter a Description that will help you identify the key later on.
3. A unique user API key will be generated. Copy it to a safe place, as you will not have access to copy this key again. Once it has been copied, click Close. If you lose a key you will need to delete it and create a new one.

Step 2: 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. Team Managers: You will need to filter by services belonging to your Team(s).

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 3: 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 4: Decide on Event Types

V3 webhook subscriptions introduce a new way to refine subscriptions with event 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 5: 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 6: 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.