PagerDuty Documentation

Our latest version of Webhooks is V3.

V3 webhooks provide the foundation for the future of PagerDuty webhooks. When compared with previous versions, they provide additional event types to signal changes to incident priorities and incident responders. They also provide additional filtering capabilities.

To get started with v3 webhooks, create a webhook subscription using the Webhook Subscriptions API.

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 Subscriptions

V3 webhooks are configured by creating a webhook subscription which contains three main components:

The set of outbound event types that are of interest
A filter or scope of the events to be delivered
The delivery method that should be used to send the matching events as a webhook

Sample Create Webhook Subscription Request

{
  "webhook_subscription": {
    "delivery_method": {
      "type": "http_delivery_method",
      "url": "https://example.com/receive_a_pagerduty_webhook",
      "custom_headers": [
        {
          "name": "your-header-name",
          "value": "your-header-value"
        }
      ]
    },
    "description": "Sends PagerDuty v3 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.status_update_published",
      "incident.triggered",
      "incident.unacknowledged"
    ],
    "filter": {
      "id": "P393ZNQ",
      "type": "service_reference"
    },
    "type": "webhook_subscription"
  }
}

Custom Headers

The custom_headers of a webhook subscription define any optional headers that will be passed along with the payload to the destination URL. The header values are redacted in GET requests, but are not redacted on the webhook when delivered to the webhook's endpoint. All header names must be unique within a webhook subscription.

Events

The events of a webhook subscription define which event types will produce webhooks for the subscription. A subset of all event types may be provided if the destination is only interested in a limited set of events.

Filter

The filter of a webhook subscription determines which events will match and produce a webhook. There are currently three types of filters that can be applied to v3 webhooks: service_reference, team_reference and account_reference.

In the case of incident events, the different filter types will only produce webhooks for the incidents that are associated with the filter object. For example: a webhook subscription with a service filter would produce webhooks for all incidents belonging to the specified service.

More Details

Please see the full Webhook Subscriptions API Reference for more details.

Webhook Payload

V3 webhook payloads are based around the concept of outbound events. V3 webhooks provide a mechanism to deliver these events to your server or application.

Each webhook payload contains a single event object. This event object contains high-level information common to all outbound events. The inner event.data payload differs based on the event.event_type and contains detailed information about the change that occurred.

Field Name	Type	Description
`event`	Object	The event that triggered the webhook.
`event.id`	String	The unique id of the event.
`event.event_type`	String	The type of the event. This usually provides a description of what happened (e.g. `incident.priority_updated`).
`event.resource_type`	String	The root resource type (leftmost part of the `event_type`) this event is about (currently `incident` or `service`). It can be different from the more specific `data.type` in the event payload.
`event.occurred_at`	DateTime	An ISO 8601 datetime indicating when the event occurred.
`event.agent`	a Resource Reference or `null`	Indicates who or what initiated the event. A `null` value might indicate an event triggered via automation rather than a specific person.
`event.client`	Object or `null`	Information about where the event was triggered.
`event.data`	Object	Data specific to the `event_type` that occurred.

An example webhook payload for an incident.priority_updated event is shown below.

{
  "event": {
    "id": "5ac64822-4adc-4fda-ade0-410becf0de4f",
    "event_type": "incident.priority_updated",
    "resource_type": "incident",
    "occurred_at": "2020-10-02T18:45:22.169Z",
    "agent": {
      "html_url": "https://acme.pagerduty.com/users/PLH1HKV",
      "id": "PLH1HKV",
      "self": "https://api.pagerduty.com/users/PLH1HKV",
      "summary": "Tenex Engineer",
      "type": "user_reference"
    },
    "client": {
      "name": "PagerDuty"
    },
    "data": {
      "id": "PGR0VU2",
      "type": "incident",
      "self": "https://api.pagerduty.com/incidents/PGR0VU2",
      "html_url": "https://acme.pagerduty.com/incidents/PGR0VU2",
      "number": 2,
      "status": "triggered",
      "incident_key": "d3640fbd41094207a1c11e58e46b1662",
      "created_at": "2020-04-09T15:16:27Z",
      "reopened_at": "2020-10-02T18:45:22Z",
      "title": "A little bump in the road",
      "service": {
        "html_url": "https://acme.pagerduty.com/services/PF9KMXH",
        "id": "PF9KMXH",
        "self": "https://api.pagerduty.com/services/PF9KMXH",
        "summary": "API Service",
        "type": "service_reference"
      },
      "assignees": [
        {
          "html_url": "https://acme.pagerduty.com/users/PTUXL6G",
          "id": "PTUXL6G",
          "self": "https://api.pagerduty.com/users/PTUXL6G",
          "summary": "User 123",
          "type": "user_reference"
        }
      ],
      "escalation_policy": {
        "html_url": "https://acme.pagerduty.com/escalation_policies/PUS0KTE",
        "id": "PUS0KTE",
        "self": "https://api.pagerduty.com/escalation_policies/PUS0KTE",
        "summary": "Default",
        "type": "escalation_policy_reference"
      },
      "teams": [
        {
          "html_url": "https://acme.pagerduty.com/teams/PFCVPS0",
          "id": "PFCVPS0",
          "self": "https://api.pagerduty.com/teams/PFCVPS0",
          "summary": "Engineering",
          "type": "team_reference"
        }
      ],
      "priority": {
        "html_url": "https://acme.pagerduty.com/account/incident_priorities",
        "id": "PSO75BM",
        "self": "https://api.pagerduty.com/priorities/PSO75BM",
        "summary": "P1",
        "type": "priority_reference"
      },
      "urgency": "high",
      "conference_bridge": {
        "conference_number": "+1 1234123412,,987654321#",
        "conference_url": "https://example.com"
      },
      "resolve_reason": null
    }
  }
}

An example webhook payload for a service.updated event is shown below.

{
  "event": {
    "id": "01BRB6ZP4M6T8ZG4X6BP63ZB9O",
    "event_type": "service.updated",
    "resource_type": "service",
    "occurred_at": "2021-03-02T13:35:11.682Z",
    "agent": null,
    "client": null,
    "data": {
      "html_url": "https://acme.pagerduty.com/services/PF9KMXH",
      "id": "PF9KMXH",
      "self": "https://api.pagerduty.com/services/PF9KMXH",
      "summary": "testing service updates",
      "alert_creation": "create_alerts_and_incidents",
      "teams": [
        {
          "html_url": "https://acme.pagerduty.com/teams/PFCVPS0",
          "id": "PFCVPS0",
          "self": "https://api.pagerduty.com/teams/PFCVPS0",
          "summary": "Engineering",
          "type": "team_reference"
        }
      ],
      "type": "service"
    }
  }
}

Event Types

Outbound events are created when PagerDuty resources change in interesting ways. Each outbound event is usually associated with some other PagerDuty resource. For example, the incident.priority_updated event is generated whenever the priority of an incident is changed. The following event types are available to v3 webhooks. Additional event types may be added to this list over time.

Event Type	`data.type`	Description	Scoped OAuth requires
incident.acknowledged	`incident`	Sent when an incident is acknowledged.	`incidents.read`
incident.annotated	`incident_note`	Sent when a note is added to an incident.	`incidents.read`
incident.conference_bridge.updated	`incident_conference_bridge`	Sent when an incident's conference bridge number and/or conference bridge url is updated.	`incidents.read`
incident.custom_field_values.updated	`incident_field_values`	Sent when an incident's custom fields values are updated.	`incidents.read`
incident.delegated	`incident`	Sent when an incident has been reassigned to another escalation policy.	`incidents.read`
incident.escalated	`incident`	Sent when an incident has been escalated to another user in the same escalation level.	`incidents.read`
incident.incident_type.changed	`incident`	Sent when an incident has changed it’s incident type.	`incidents.read`
incident.priority_updated	`incident`	Sent when the priority of an incident has changed.	`incidents.read`
incident.reassigned	`incident`	Sent when an incident has been reassigned to another user.	`incidents.read`
incident.reopened	`incident`	Sent when an incident is reopened.	`incidents.read`
incident.resolved	`incident`	Sent when an incident is resolved.	`incidents.read`
incident.responder.added	`incident_responder`	Sent when a responder has been added to an incident.	`incidents.read`
incident.responder.replied	`incident_responder`	Sent when a responder replies to a request.	`incidents.read`
incident.role.assigned	`incident_role_assignment`	Sent when an incident role is assigned or unassigned.	`incidents.read`
incident.service_updated	`incident`	Sent when the service of an incident has changed.	`incidents.read`
incident.status_update_published	`incident_status_update`	Sent when a status update is added to an incident.	`incidents.read`
incident.task.completed	`incident_task`	Sent when an incident task is completed.	`incidents.read`
incident.task.created	`incident_task`	Sent when an incident task is created.	`incidents.read`
incident.task.updated	`incident_task`	Sent when an incident task is updated.	`incidents.read`
incident.triggered	`incident`	Sent when an incident is newly created/triggered.	`incidents.read`
incident.unacknowledged	`incident`	Sent when an incident is unacknowledged.	`incidents.read`
incident.action_invocation.created	`incident_action_invocation`	Sent when an incident action invocation is created.	`incidents.read`
incident.action_invocation.terminated	`incident_action_invocation`	Sent when an incident action invocation is terminated.	`incidents.read`
incident.action_invocation.updated	`incident_action_invocation`	Sent when an incident action invocation is updated.	`incidents.read`
incident.workflow.started	`incident_workflow_instance`	Sent when an incident workflow starts.	`incident_workflows.read`
incident.workflow.completed	`incident_workflow_instance`	Sent when an incident workflow completes.	`incident_workflows.read`
service.created	`service`	Sent when a service is created.	`services.read`
service.custom_field_values.updated	`service_field_values`	Sent when an service's custom fields values are updated.	`services.read`
service.deleted	`service`	Sent when a service is deleted.	`services.read`
service.updated	`service`	Sent when a service is updated.	`services.read`

Event Data Types

Depending on the event.event_type, of the webhook payload, the event.data field will contain one of the objects described in this section.

incident

{
  "id": "PGR0VU2",
  "type": "incident",
  "self": "https://api.pagerduty.com/incidents/PGR0VU2",
  "html_url": "https://acme.pagerduty.com/incidents/PGR0VU2",
  "number": 2,
  "status": "triggered",
  "incident_key": "d3640fbd41094207a1c11e58e46b1662",
  "created_at": "2020-04-09T15:16:27Z",
  "reopened_at": "2020-10-02T18:45:22Z",
  "title": "A little bump in the road",
  "incident_type": {
    "name": "major"
  },
  "service": {
    "html_url": "https://acme.pagerduty.com/services/PF9KMXH",
    "id": "PF9KMXH",
    "self": "https://api.pagerduty.com/services/PF9KMXH",
    "summary": "API Service",
    "type": "service_reference"
  },
  "assignees": [
    {
      "html_url": "https://acme.pagerduty.com/users/PTUXL6G",
      "id": "PTUXL6G",
      "self": "https://api.pagerduty.com/users/PTUXL6G",
      "summary": "User 123",
      "type": "user_reference"
    }
  ],
  "escalation_policy": {
    "html_url": "https://acme.pagerduty.com/escalation_policies/PUS0KTE",
    "id": "PUS0KTE",
    "self": "https://api.pagerduty.com/escalation_policies/PUS0KTE",
    "summary": "Default",
    "type": "escalation_policy_reference"
  },
  "teams": [
    {
      "html_url": "https://acme.pagerduty.com/teams/PFCVPS0",
      "id": "PFCVPS0",
      "self": "https://api.pagerduty.com/teams/PFCVPS0",
      "summary": "Engineering",
      "type": "team_reference"
    }
  ],
  "priority": {
    "html_url": "https://acme.pagerduty.com/account/incident_priorities",
    "id": "PSO75BM",
    "self": "https://api.pagerduty.com/priorities/PSO75BM",
    "summary": "P1",
    "type": "priority_reference"
  },
  "urgency": "high",
  "conference_bridge": {
    "conference_number": "+1 1234123412,,987654321#",
    "conference_url": "https://example.com"
  },
  "resolve_reason": null
}

incident_conference_bridge

{
  "incident": {
    "html_url": "https://acme.pagerduty.com/incidents/PGR0VU2",
    "id": "PGR0VU2",
    "self": "https://api.pagerduty.com/incidents/PGR0VU2",
    "summary": "Major incident - customer shopping cart screen",
    "type": "incident_reference"
  },
  "conference_numbers": [
    {
      "label": "",
      "number": "+1-555-555-5555"
    }
  ],
  "conference_url": "https://example.com",
  "type": "incident_conference_bridge"
}

incident_field_values

{
  "incident": {
    "html_url": "https://acme.pagerduty.com/incidents/PBAZLIU",
    "id": "PBAZLIU",
    "self": "https://api.pagerduty.com/incidents/PBAZLIU",
    "summary": null,
    "type": "incident_reference"
  },
  "custom_fields": [
    {
      "data_type": "string",
      "field_type": "single_value",
      "id": "PICFVXX",
      "name": "environment",
      "namespace": "incidents",
      "type": "field_value",
      "value": "production"
    },
    {
      "data_type": "string",
      "field_type": "single_value",
      "id": "PF3UUI7",
      "name": "region",
      "namespace": "incidents",
      "type": "field_value",
      "value": "US"
    }
  ],
  "changed_custom_fields": [
    {
      "data_type": "string",
      "field_type": "single_value",
      "id": "PICFVXX",
      "name": "environment",
      "namespace": "incidents",
      "type": "field_value",
      "value": "staging"
    }
  ],
  "type": "incident_field_values"
}

incident_note

{
  "incident": {
    "html_url": "https://acme.pagerduty.com/incidents/PGR0VU2",
    "id": "PGR0VU2",
    "self": "https://api.pagerduty.com/incidents/PGR0VU2",
    "summary": "A little bump in the road",
    "type": "incident_reference"
  },
  "id": "P2LA89X",
  "content": "I sure am glad we are using PagerDuty!",
  "trimmed": false,
  "type": "incident_note"
}

incident_role_assignment

{
    "type": "incident_role_assignment",
    "incident_role_assignments": [
      {
        "assignee": {
          "html_url": "https://acme.pagerduty.com/users/P75B6QD",
          "id": "P75B6QD",
          "self": "https://api.pagerduty.com/users/P75B6QD",
          "summary": "User 1810194",
          "type": "user_reference"
        },
        "id": "af64b84c-137e-40c6-875c-5dd30a2afaaa",
        "incident": {
          "html_url": "https://acme.pagerduty.com/incidents/PBAZLIU",
          "id": "PBAZLIU",
          "self": "https://api.pagerduty.com/incidents/PBAZLIU",
          "summary": null,
          "type": "incident_reference"
        },
        "old_assignee": null,
        "role": {
          "id": "P8PQO4R",
          "summary": "Role Display Name",
          "type": "role_reference"
        },
        "status": "active",
        "type": "role_assignment_reference"
      }
    ]
  }

incident_status_update

{
  "incident": {
    "html_url": "https://acme.pagerduty.com/incidents/PGR0VU2",
    "id": "PGR0VU2",
    "self": "https://api.pagerduty.com/incidents/PGR0VU2",
    "summary": "A little bump in the road",
    "type": "incident_reference"
  },
  "id": "P2LA89X",
  "message": "A fix for this incident is being developed",
  "trimmed": false,
  "type": "incident_status_update"
}

incident_responder

{
  "incident": {
    "html_url": "https://acme.pagerduty.com/incidents/PGR0VU2",
    "id": "PGR0VU2",
    "self": "https://api.pagerduty.com/incidents/PGR0VU2",
    "summary": "A little bump in the road",
    "type": "incident_reference"
  },
  "user": {
    "html_url": "https://acme.pagerduty.com/users/PVMGSML",
    "id": "PVMGSML",
    "self": "https://api.pagerduty.com/users/PVMGSML",
    "summary": "Maeve",
    "type": "user_reference"
  },
  "escalation_policy": {
    "html_url": "https://acme.pagerduty.com/escalation_policies/PJFWPEP",
    "id": "PJFWPEP",
    "self": "https://api.pagerduty.com/escalation_policies/PJFWPEP",
    "summary": "The Policy",
    "type": "escalation_policy_reference"
  },
  "message": "Please help me make the tests pass",
  "state": "pending",
  "type": "incident_responder"
}

incident_task

{
  "name": "A thing that needs to be done",
  "description": "A description of the task",
  "id": "PGR0VU2",
  "summary": "A thing that needs to be done",
  "type": "incident_task",
  "status": "todo",
  "assignees": [
    {
      "html_url": "https://acme.pagerduty.com/users/PIV35G6",
      "id": "PIV35G6",
      "self": "https://api.pagerduty.com/users/PIV35G6",
      "summary": "User 661768438",
      "type": "user_reference"
    }
  ],
  "incident": {
    "html_url": "https://acme.pagerduty.com/incidents/Q0SDD3HB6SGFTI",
    "id": "Q0SDD3HB6SGFTI",
    "self": "https://api.pagerduty.com/incidents/Q0SDD3HB6SGFTI",
    "summary": null,
    "type": "incident_reference"
  }
}

incident_workflow_instance

{
  "id": "P3SNKQS",
  "type": "incident_workflow_instance",
  "summary": "A Workflow Instance Name",
  "incident_workflow": {
    "html_url": "https://acme.pagerduty.com/incident-workflows/workflows/PSFEVL7",
    "id": "PSFEVL7",
    "self": "https://api.pagerduty.com/incident_workflows/PSFEVL7",
    "summary": "A Workflow Name",
    "type": "incident_workflow_reference"
  },
  "workflow_trigger": {
    "html_url": null,
    "id": "4ad696eb-bb48-422a-8bd0-6efad6befa29",
    "self": "https://api.pagerduty.com/incident_workflows/triggers/4ad696eb-bb48-422a-8bd0-6efad6befa29",
    "summary": "Trigger Name",
    "type": "workflow_trigger_reference"
  },
  "incident": {
    "html_url": "https://acme.pagerduty.com/incidents/PBAZLIU",
    "id": "PBAZLIU",
    "self": "https://api.pagerduty.com/incidents/PBAZLIU",
    "summary": "A little bump in the road",
    "type": "incident_reference"
  },
  "service": {
    "html_url": "https://acme.pagerduty.com/services/PF9KMXH",
    "id": "PF9KMXH",
    "self": "https://api.pagerduty.com/services/PF9KMXH",
    "summary": "A service",
    "type": "service_reference"
  }
}

service

{
  "html_url": "https://acme.pagerduty.com/services/PF9KMXH",
  "id": "PF9KMXH",
  "self": "https://api.pagerduty.com/services/PF9KMXH",
  "summary": "testing service updates",
  "alert_creation": "create_alerts_and_incidents",
  "teams": [
    {
      "html_url": "https://acme.pagerduty.com/teams/PFCVPS0",
      "id": "PFCVPS0",
      "self": "https://api.pagerduty.com/teams/PFCVPS0",
      "summary": "Engineering",
      "type": "team_reference"
    }
  ],
  "type": "service"
}

service_field_values

{
  "service": {
    "html_url": "https://acme.pd-staging.com/services/PY0TW31",
    "id": "PY0TW31",
    "self": "https://api.pd-staging.com/services/PY0TW31",
    "summary": null,
    "type": "service_reference"
  },
  "custom_fields": [
    {
      "data_type": "string",
      "field_type": "multi_value",
      "id": "P0CU101",
      "name": "string_multi_example_1",
      "type": "field_value",
      "value": [
        "1",
        "2"
      ]
    },
    {
      "data_type": "string",
      "field_type": "single_value",
      "id": "P7DNIMB",
      "name": "example_field",
      "type": "field_value",
      "value": "Some new value"
    }
  ],
  "changed_custom_fields": [
    {
      "data_type": "string",
      "field_type": "single_value",
      "id": "P7DNIMB",
      "name": "example_field",
      "type": "field_value",
      "value": "Some old value"
    }
  ],
  "type": "service_field_values"
}

incident_action_invocation

{
  "id": "01CELD6T9C2JS745I7CAK0LRRF",
  "self": "https://api.pagerduty.com/automation/invocations/01CELD6T9C2JS745I7CAK0LRRF",
  "html_url": "https://acme.pagerduty.com/rundeck-actions/actions/01CDYN0IRV4VG991K5FR73YNTW/invocations/01CELD6T9C2JS745I7CAK0LRRF/report",
  "incident": {
    "html_url": "https://acme.pagerduty.com/incidents/PBAZLIU",
    "id": "PBAZLIU",
    "self": "https://api.pagerduty.com/incidents/PBAZLIU",
    "summary": "An Incident",
    "type": "incident_reference"
  },
  "action": {
    "html_url": "https://acme.pagerduty.com/rundeck-actions/actions/01CDYN0IRV4VG991K5FR73YNTW",
    "id": "01CDYN0IRV4VG991K5FR73YNTW",
    "self": "https://api.pagerduty.com/automation/actions/01CDYN0IRV4VG991K5FR73YNTW",
    "summary": "A Helpful Action",
    "type": "action_reference"
  },
  "state": "created",
  "type": "incident_action_invocation"
}

Early Access Events

In addition to the events detailed on this page, we may occasionally have Early Access events. These are subject to change at any moment, without notice.

Deprecated Versions

V1 Webhooks Reached End Of Life

V1 reached End-Of-Support (EOS) in November 2021.
V1 reached End-Of-Life (EOL) in October 2022.

V2 Webhooks Reached End Of Support

V2 reached End-Of-Support (EOS) in October 2022.
Please see the note at the top of this document for up-to-date V2 End-Of-Life information.

What is EOS & EOL?

EOS means PagerDuty will not support any additional bug fixes or entertain new feature requests.

EOL means PagerDuty will end the functionality and it won't be available for anyone to use.

Overview

Migrate to V3 Webhook Subscriptions