Alert through PagerDuty
A PagerDuty channel turns a check’s problems into one PagerDuty incident and resolves it when the check recovers. Pingwell sends through PagerDuty’s Events API v2; nothing comes back the other way, so acknowledging in PagerDuty changes nothing in Pingwell.
Connect a service
- In PagerDuty, open the service that should page and go to Integrations → Add integration → Events API v2.
- Copy the integration key (32 characters).
- In Pingwell, open Alerts → Add alert channel → PagerDuty. Paste the key, pick the region your PagerDuty account lives in (United States or European Union), and add the channel.
The region picks the endpoint: events.pagerduty.com for a US-hosted account, events.eu.pagerduty.com for an EU-hosted one. A key from an EU account is refused on the US endpoint, and the other way round, so the alert dies with PagerDuty’s message until the region matches.
The key is kept and never shown again. Put the channel in a group or on the checks that should page, like any other channel.
What pages, and when
| In Pingwell | In PagerDuty |
|---|---|
| A monitor or heartbeat goes down | An incident opens, severity critical |
| A monitor is degraded, or a heartbeat is late, and still is two minutes later | An incident opens, severity warning |
| The check recovers | The incident resolves |
Every event about one check carries the same dedup key, pingwell:monitor:<id> or pingwell:heartbeat:<id>, so a check has one open incident at a time. A warning followed by a down raises that incident instead of opening a second one; the recovery resolves it. A recovery is sent only to a channel that heard about the problem, so Pingwell never resolves an incident it did not open.
The incident’s summary is the alert’s headline in the channel’s language, with the failing regions or the heartbeat’s reason. custom_details carries the check (type, id and name), the event, the reason and a link to the check in Pingwell; so does the incident’s Open in Pingwell link.
Test
Send test on the channel opens a test incident at severity info on its own key and resolves it straight away. Whether an info event pages anyone is your service’s urgency rule in PagerDuty.
Replacing the key
Open the channel’s settings and paste a new key under Replace integration key; leave the field empty to keep the current one. The region can be changed there too.
Failures
A key PagerDuty refuses marks the alert dead at once, with PagerDuty’s message, on the channel’s page. A rate limit or an outage on their side is retried after 30 s, 2 min, 10 min and 30 min, like a webhook.