Webhooks
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 or use our migration script (provided as is).
- An end-of-life date for V2 webhooks has not been set. However, end-of-support for V2 webhooks began on October 31, 2022. This means existing integrations based on V2 webhooks will continue to work, however PagerDuty cannot accept any new feature requests or implement bug fixes.
- V1 webhook extensions became unsupported on November 13, 2021 and lost functionality on October 31, 2022.
- Please see Webhook V1 Alternatives for a list of affected integrations and alternative solutions.
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.
Manage V3 Webhook Subscriptions
There are two places where you can manage V3 webhook subscriptions:
Required User Permissions
Users with the following roles can manage V3 webhook subscriptions:
- Manager base role (for service-level and Team-level webhooks)
- Users with a Manager Team role (for service-level and Team-level webhooks associated with their Teams)
- Admin/Global Admin
- Account Owner
If, due to your user role (e.g., a Restricted Access user with a Manager Team role), you do not see Integrations in the top navigation bar, you can manage V3 webhook subscriptions on the Service Details Page.
Product Limit
You can create up to 10 webhook subscriptions per unique service and Team ID (e.g.,
PXXXXXX
), as well as for the account-level scope. Attempts to create additional webhook subscriptions will generate an error:Failed to create webhook. Webhook subscription limit exceeded for the selected scope.
You can read more about the Product Limit Reached error code (2019) in our developer documentation: PagerDuty Error Codes.
Add a V3 Webhook Subscription on the Generic Webhooks Page
- Navigate to Integrations Generic Webhooks (v3).
- Click New Webhook and then perform the following:
- Webhook URL: Enter the webhook URL.
- Description (optional): Enter an optional description.
- Event Subscription: Select the event types that you would like to subscribe to.
- Custom Header (optional): You may optionally create a custom header by entering a Name and Value.
- Click Add Webhook.
- A confirmation dialog will appear notifying you that the webhook has been created, and it will supply a secret if you would like to verify webhook payloads.
Edit a V3 Webhook Subscription on the Generic Webhooks Page
- Navigate to Integrations Generic Webhooks (v3).
- Select the webhook’s URL or select Manage.
- Click Edit and make the required changes.
- Click Save Changes.
Delete a V3 Webhook Subscription on the Generic Webhooks Page
- Navigate to Integrations Generic Webhooks (v3).
- To the right of the webhook you would like to delete, select Delete.
- A confirmation dialog will appear. Click Delete to delete the webhook.
Add a V3 Webhook Subscription on the Service Details Page
- Navigate to Services Service Directory select the service where you would like to add the webhook subscription.
- Select the Integrations tab, scroll to the Webhooks section and then click Add or manage webhooks for this service.
No V3 Webhooks Found on this Service
If this is the first webhook subscription on the service, you will see No V3 webhooks found on this service. Click Webhook to manage webhook subscriptions on the service, and continue to step 3.
- Click New Webhook and then perform the following:
- Webhook URL: Enter the webhook URL.
- Description (optional): Enter an optional description.
- Event Subscription: Select the event types that you would like to subscribe to.
- Custom Header (optional): You may optionally create a custom header by entering a Name and Value.
- Click Add Webhook.
- A confirmation dialog will appear notifying you that the webhook has been created, and it will supply a secret if you would like to verify webhook payloads.
Edit a V3 Webhook Subscription on the Service Details Page
- Navigate to Services Service Directory select the service where you would like to edit the webhook subscription.
- Select the Integrations tab, scroll to the Webhooks section and click Add or manage webhooks for this service.
- Select the webhook’s URL or select Manage.
- Click Edit and make the required changes.
- Click Save Changes.
Delete a V3 Webhook Subscription on the Service Details Page
- Navigate to Services Service Directory select the service where you would like to delete the webhook subscription.
- Select the Integrations tab, scroll to the Webhooks section and click Add or manage webhooks for this service.
- To the right of the webhook you would like to delete, select Delete.
- A confirmation dialog will appear. Click Delete to delete the webhook.
Send a Test Event
To test that your webhook is configured correctly and that payloads arrive at the other end:
- Navigate to Integrations Generic Webhooks (v3).
- Select the webhook’s URL or Manage.
- Under Test select Send Test Event.
- 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"
}
}
}
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 |
conference_bridge.updated | Sent when a conference bridge is updated |
custom_field_values.updated | Sent when Custom Field values are updated |
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 |
priority_updated | Sent when the priority of an incident has changed |
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 |
responder.added | Sent when a responder has been added to an incident |
responder.replied | Sent when a responder replies to a request |
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 |
workflow.completed | Sent when an Incident Workflow finishes |
workflow.started | Sent when an Incident Workflow begins |
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 |
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.
Incident ID
In Webhooks v3, the incident ID is found in a different payload location than earlier versions. Developers can use the following code snippet to accurately extract the incident ID:
if event.data.type == "incident" {
incident_id = event.data.id
} else {
incident_id = event.data.incident.id
}
Custom Headers
You can add custom headers to V3 webhook subscriptions in the web app:
- Go to Integrations Generic Webhooks (v3).
- Click New Webhook to create a new webhook subscription, or select an existing webhook and click Edit.
- In the section Custom Headers, click Add custom header.
- In the fields Name and Value, enter an appropriate name and value for your header.
- Note: If you add more than one custom header, please note that each header must have a unique Name.
- Click Save Changes.
After saving changes, custom headers’ value will be redacted for security’s sake.
Delete a Custom Header
- Go to Integrations Generic Webhooks (v3).
- Select a webhook and click Edit.
- In the section Custom Headers, click to the right of the custom header you’d like to delete.
- Click Save Changes.
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
.
Version Comparison
V3 webhook subscriptions offer more event types than previous versions. Please reference the table below for an overview. Also, please note that some event types have a slight name difference between versions, e.g., trigger
(v1 and v2) and triggered
(v3).
Resource | Event | v1 | v2 | v3 |
---|---|---|---|---|
Incident | trigger /triggered | ✓ | ✓ | ✓ |
acknowledge /acknowledged | ✓ | ✓ | ✓ | |
unacknowledge /unacknowledged | ✓ | ✓ | ✓ | |
resolve /resolved | ✓ | ✓ | ✓ | |
assign | ✓ | ✓ | ✓ | |
escalate /escalated | ✓ | ✓ | ✓ | |
delegate /delegated | ✓ | ✓ | ✓ | |
annotate /annotated | ✓ | ✓ | ||
priority_updated | ✓ | |||
reassigned | ✓ | |||
reopened | ✓ | |||
responder.added | ✓ | |||
responder.replied | ✓ | |||
status_update_published | ✓ | |||
conference_bridge.updated | ✓ | |||
custom_field_values.updated | ✓ | |||
workflow.completed | ✓ | |||
workflow.started | ✓ | |||
Service | created | ✓ | ||
deleted | ✓ | |||
updated | ✓ |
Migrate from V1/V2 Generic Extensions to V3 Webhook Subscriptions
There are two options to migrate to V3 Webhook Subscriptions:
- Follow our Migration Guide below.
- Use our migration script (provided as is).
Migration Guide
The following guide explains how to migrate existing V1/V2 generic webhook extensions to V3 webhook subscriptions. End-of-support for V2 webhooks began on October 31, 2022, and an end-of-life date is TBD. V1 webhook extensions became unsupported on November 13, 2021 and lost functionality in October, 2022.
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:
- Generate an API key by navigating to Integrations API Access Keys Create New API Key.
- 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.
- 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.
- Generate a user API key by navigating to User Icon My Profile User Settings tab Create API User Token.
- Enter a Description that will help you identify the key later on.
- 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. If the extension has a name other than Generic Webhook, use that name in the query
field instead. 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.
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 6: Cleanup
At this point, a new V3 webhook subscription has been created that will replicate the existing V1 or V2 generic webhook extension. Duplicate webhooks will be sent so long as both V1/V2 and V3 subscriptions exist. Once it is confirmed that the new V3 webhook subscription is functional, the old 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 25 days ago
You can read more about PagerDuty Webhooks in our Developer Docs here: