PagerDuty Integration: Page On-Call from a Monitor

A PagerDuty integration is the link between a system that noticed something and a person whose phone will ring. It is built from three pieces: a service, an integration key, and events posted to the Events API. Get the key right and the rest is a single HTTP call you can test in a terminal today.

What is a PagerDuty integration?

It is a named connection attached to a PagerDuty service that accepts events from one outside system. The service owns the escalation policy, so the integration decides where an alert lands and the policy decides who it wakes. Each integration carries its own key, which PagerDuty calls the Integration Key and the Events API calls the routing_key.

Most monitoring tools use Events API v2 rather than a bespoke connector. PagerDuty's own documentation describes that path as the one for machine-generated monitoring data and external site checks. If your tool is not in the directory of named integrations, this is the route you take.

Getting the integration key

Every PagerDuty integration hands you one key at creation time, and that key is the only thing you need to copy out. Five clicks gets you there.

1. Open Services, then Service Directory, and select the service that should receive the events.
2. Click the Integrations tab and choose Add another integration.
3. Search for Events API v2 and add it.
4. Expand the new row with the chevron to reveal the Integration Key.
5. Store the key in your secret manager, because it is a credential that can open incidents.

One key per source is the habit worth forming. A shared key across four systems makes the noisy one impossible to disable without silencing the other three.

Sending your first event

The endpoint is the same for everyone and takes no authorization header. The routing key inside the body is the credential.

curl -X POST https://events.pagerduty.com/v2/enqueue \
  -H 'Content-Type: application/json' \
  -d '{
    "routing_key": "R0XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "event_action": "trigger",
    "dedup_key": "checkout-api-down",
    "payload": {
      "summary": "DOWN: checkout API returned 503",
      "source": "uptime-probe-london",
      "severity": "critical",
      "custom_details": { "confirmed_from": "london, singapore", "last_good": "14:02:31Z" }
    }
  }'

A good call returns 202 with a small JSON body containing status: success and the deduplication key. We tested the failure modes too, on 23 September 2026. Omitting payload.severity returns an invalid event body naming the missing field. A severity of panic returns an error listing the only four that are legal, which are critical, error, warning and info.

Three fields are mandatory inside payload, and the Events API v2 reference is the place to confirm the rest. Keep summary short enough to read on a lock screen, because that is where it is going to be read. Put the diagnostic detail in custom_details, where it sits on the incident without crowding the notification.

Why did a bad routing key still return 202?

Because the enqueue endpoint accepts the event first and resolves the key afterwards. We posted a syntactically valid but entirely made-up 32 character key and got 202 with Event processed back. Nothing arrived anywhere. A key of abc is rejected, but only because it is the wrong shape.

This is the single most expensive thing to learn during an outage rather than before one. Treat a 202 as proof that your network path and JSON are fine, and nothing more. The only real test is watching an incident open in the PagerDuty web interface, so trigger one deliberately and resolve it by hand the day you wire this up.

Closing the incident with a dedup key

dedup_key is what turns two events into one incident with a lifecycle. Send a trigger with a key, send more triggers with the same key, and PagerDuty keeps updating one incident instead of opening five. Send resolve with that key and the incident closes on its own.

curl -X POST https://events.pagerduty.com/v2/enqueue \
  -H 'Content-Type: application/json' \
  -d '{"routing_key":"R0XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
       "event_action":"resolve","dedup_key":"checkout-api-down"}'

We ran this against a made-up key and the response echoed our own dedup_key straight back, which confirms the field is accepted verbatim rather than rewritten. Derive it from something stable such as the monitor identifier. A key built from a timestamp guarantees every recovery orphans the incident it was meant to close.

Wiring a monitor to your PagerDuty integration

The state machine does the deciding before any event is sent. A check goes UP to SUSPECT to DOWN, and only a DOWN confirmed from a second region is worth a page. Create the monitor with two regions and a failure threshold, then attach the alert channel that holds your key.

curl -X POST https://uptimeroom.com/api/v1/monitors \
  -H "Authorization: Bearer urm_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "checkout api",
    "type": "http",
    "target": "https://example.com/api/checkout/health",
    "intervalSec": 60,
    "regions": ["london", "singapore"],
    "alertAfterCycles": 2
  }'

PagerDuty sits among the 16 alert channel types, so the key is pasted into a channel once and reused across monitors. Channel payload fields are listed in the REST API reference. Attach the channel per monitor rather than to everything, for the reasons set out in alert fatigue.

Which events deserve to page someone?

Not many. The point of routing through a paging tool is that the channel it feeds has real consequences, so the filter belongs upstream of it.

Event	PagerDuty severity	Pages out of hours
Public endpoint DOWN, confirmed from two regions	critical	yes
Single unconfirmed probe failure	nothing sent	no
Response time over threshold for ten minutes	warning	no
Certificate expiring in 14 days	info	no
Missed heartbeat on a nightly batch job	warning	no
Recovery	resolve event	no

The second row is the one that decides whether anyone trusts the pipe. One failed probe is a blip, and a probe error never counts as a down vote in the first place.

Severity is not the same lever as urgency. Severity travels in the event and describes the thing that broke, while urgency is decided by the service and the policy sitting behind it. Map the two deliberately, or a warning about a certificate will ring a phone at four in the morning.

Common mistakes

Paging on the first failed check. Confirmation exists so that a routing wobble in one region does not become a phone call. Set alertAfterCycles to 2 and let the second region agree before anything reaches the enqueue endpoint.

Reusing one integration key everywhere. Keys are how you disable a source. Sharing one across your checker, your log pipeline and a cron script means the only mute button is the whole service. Give each source its own PagerDuty integration on the same service instead, which costs nothing and keeps the off switch fine-grained.

Sending a trigger without a resolve. An incident that a human has to close by hand is an incident that stays open until someone notices, and MTTR numbers built on manual closes are fiction. Details on that measurement live in MTTR and MTBF.

Expecting the checker to hold the rota. On-call schedules, escalation ladders and overrides belong in the paging tool. An external probe supplies the event and the confirmation behind it, and PagerDuty decides whose night it is.

Wire it in this order and the whole thing takes an afternoon. Create the service, copy the key, prove the path with curl, then send one deliberate trigger and one resolve before you trust it. A PagerDuty integration is only as good as the confirmation sitting in front of it, which is why two-region agreement is part of the free plan rather than an upgrade. Start there, then widen the regions once the noise level is known.