PagerDuty Events API v2 for outages
Published . Updated .
This guide explains how a down check opens a PagerDuty incident and how the recovery resolves the same incident, using the integration key on the service.
Create an Events API v2 integration on the PagerDuty service that should page, copy the 32-character integration key, and paste it on the PagerDuty card. A down sends event_action trigger. An up sends resolve with the same dedup_key. A client can use a different key when that client has its own service.
Where the key comes from
PagerDuty's Events API v2 overview says to create an integration on a service, choose Events API v2 as the integration type, and send the integration key as routing_key. The send-an-alert page says that key is 32 characters and that the endpoint is https://events.pagerduty.com/v2/enqueue.
This pass did not click through a live PagerDuty account, so it does not add button names beyond those docs. In the docs, the key is on the service integration. Copy the integration key, not an API token from the user menu, and not a key that starts with a different product's prefix. The field accepts 32 letters and digits.
Paste the key on Alerting, then PagerDuty. It is stored encrypted and it is not shown again.
How a down and an up map
A down is event_action trigger. The payload summary is the check name and the word down. The source is the target URL. The severity is critical. The dedup_key is watchbill: then the check id, then :outage.
An up is event_action resolve with the same routing_key and the same dedup_key. PagerDuty's send-an-alert page says resolve moves that incident to resolved, and a later trigger with the same key opens a new incident rather than reopening the old one. That matches one outage: one trigger, one resolve.
There is no acknowledge event. Someone acknowledging in PagerDuty is your process, not a message from the check.
A test sends a trigger. It can page the service. Use a service that will not wake the on-call, or send the test while you are the one on call and resolve it in PagerDuty if you do not want to wait for a real recovery. The test does not open an outage and it does not send the resolve by itself.
A different service per client
The account key is the default for clients that inherit the account set. Add another PagerDuty destination when a client has its own service, then on that client choose Use a set on this client and check that destination. You can also assign one key to selected clients. A client with its own set keeps that set until you edit it.
The card lists the clients that use the key. All clients means every inheriting client. No clients means the key is limited to a selection that is empty, or every client has a set that does not include it.
If the incident does not open
Count the key. It is 32 characters. A key with a space or a line break will be rejected before it is sent.
PagerDuty answers 202 when it accepts the event. A 429 or a 500 is retried on the same schedule as a webhook: 60 seconds, 5 minutes, 15 minutes, then 60 minutes. The send waits 8 seconds. Another 400-class response stops. Five terminal failures turn the destination off.
If trigger works and resolve does not, the dedup key changed. Do not edit the check id. The key is derived from it. A resolve for a dedup key PagerDuty has never seen does not fail the outage. The send-an-alert page says a resolve with nothing open is a success and does not open a new incident.
Put the service name in your runbook next to the client. The integration key is not a good label. It is a secret, and it all looks the same after the first few characters. The alerting card shows the clients that use the destination. That list is the label. If the on-call rotation changes, you change it in PagerDuty. You do not paste a new key unless you created a new integration.
A flap that is confirmed down and then confirmed up sends one trigger and one resolve. A check that never confirms does not page. That is the same two-minute rule as the email. If PagerDuty shows a trigger with no resolve, the check is still down or the resolve was rejected. Look at the destination status before you assume the recovery was skipped on purpose.
Two checks that share a name still have different dedup keys, because the key uses the check id. You can rename a check without opening a second incident for the one that is already open. The resolve still finds it. A new check is a new key, which is what you want. If you delete a check and add it again, that is a new id and a new incident the next time it goes down. The old incident will not resolve from the new check at all.
How The Watchbill helps
On Pro and Business, a down sends a PagerDuty trigger and the recovery sends a resolve with the same dedup key. The key is the Events API v2 integration key. Checking mail and the first confirmed up do not page. Ticket email, Teams, and a signed webhook can run beside it. They are separate cards.
Sources
- PagerDuty docs, Events API v2 overview. Accessed October 10, 2026.
- PagerDuty docs, send an alert event. Accessed October 10, 2026.