PagerDuty Events API to On-Call

Many monitoring tools only ship a built-in "send to PagerDuty" integration. CallHeim accepts PagerDuty's own Events API wire format (v1 and v2) directly, so pointing that tool's endpoint at your CallHeim ingest URL instead of PagerDuty's is enough — the tool does not need reconfiguring beyond the URL. Alerts become CallHeim alerts, repeats collapse, and the service the integration is bound to pages whoever is on call for it. CallHeim includes a payload mapping for PagerDuty's Events API’s webhook format, built and tested against sample payloads.

How the alert reaches on-call

Step 1A monitoring tool's own built-in "PagerDuty" integration sends an Events API v2 (or legacy v1) body.
Step 2It POSTs to your CallHeim ingest URL instead of events.pagerduty.com — the only change needed at the sender.
Step 3CallHeim reads dedup_key (or incident_key) as the identity signal when the sender supplies one, and maps payload.severity.
Step 4A trigger event opens or attaches to an incident; an acknowledge or resolve event changes its state, exactly as PagerDuty's own API distinguishes them.
Step 5The integration's bound service selects an escalation policy, which pages the on-call tier.

Setting it up

01
Create the PagerDuty Events API integration in CallHeim.
This gives you an ingest URL shaped for this source.
02
In the sending tool, use its existing "PagerDuty" or "PagerDuty Events API v2" integration setting.
Replace the target URL (normally events.pagerduty.com/v2/enqueue) with your CallHeim ingest URL. Leave the tool's own routing/integration key field as-is — CallHeim treats it as an opaque value, not as authentication (see Security below).
03
A tool that hard-codes events.pagerduty.com and offers no URL override cannot be repointed this way.
Check the tool's own PagerDuty integration settings for a custom endpoint or base URL field before assuming this route works for it.

Example payloadJSON

{
  "routing_key": "your-callheim-integration-key",
  "event_action": "trigger",
  "dedup_key": "web-store-5xx",
  "payload": {
    "summary": "5xx error rate elevated on web-store",
    "source": "web-store-prod-1",
    "severity": "critical",
    "component": "checkout",
    "custom_details": { "count": 42 }
  }
}

Example shape written by us, matching PagerDuty's own documented Events API v2 request body; check PagerDuty's developer documentation for the full schema.

What CallHeim reads from the payload

Payload fields and what each one maps to on the incident
Payload field	Maps to	Note
payload.summary / description (v1) / summary	incident title
payload.severity (critical / error / warning / info)	severity	critical→P1, error→P2, warning→P3, info→P4; an event_action of resolve always writes P4 regardless of severity.
payload.source / component / group / class / custom_details / description (v1)	incident body
dedup_key (v2) or incident_key (v1)	identity signal	Only an explicit key populates the identity; without one, CallHeim hashes the summary and source instead.
event_action (v2) / event_type (v1): trigger / acknowledge / resolve	lifecycle	The one field in this guide's twelve sources that CallHeim reads directly for state, rather than inferring it.

How CallHeim processes it

Routing

Each alert source is bound to a service, and the service’s escalation policy (or its team’s) sets who is paged.

Deduplication

Repeats of the same alert collapse onto one incident while they keep arriving within five minutes of each other. A repeat that arrives after a longer quiet gap opens a new incident. For this source the fingerprint honours the sender's own dedup_key (or incident_key) when supplied — the same identity PagerDuty's own API uses to attach a follow-up acknowledge or resolve to the right alert — and falls back to a hash of the summary and source when the sender does not send one.

Recovery

PagerDuty's wire format names its lifecycle fields in a way CallHeim's recovery detection recognises: event_action (or the legacy event_type) of resolve closes the alert at P4, and acknowledge is recognised as a state change too. It still needs a live sender using PagerDuty's own wire format to actually exercise, so treat it as how the code is built and tested on hand-written payloads, not as a proven live behaviour yet.

Troubleshooting

Common problems and how to fix them
Problem	Fix
The tool refuses to send anywhere but events.pagerduty.com.	Some tools hard-code the endpoint with no override field — those cannot be repointed this way; use a source-specific CallHeim integration for that tool instead, if one exists.
HTTP 400 on send.	Check whether the sender is using v1 (service_key, event_type, description) or v2 (routing_key, event_action, payload.summary) — the two have different required fields, and mixing them produces an incomplete body.
Repeats open separate incidents.	The sender is not supplying a stable dedup_key, so identity falls back to a hash of summary and source — if either varies slightly between sends, they will not collapse.
A resolve does not close the incident.	Confirm the sender actually sets event_action to resolve (not a custom status string) and reuses the same dedup_key as the original trigger.
HTTP 401 once you enabled signing.	Whether the sending tool can add X-ItOnCall-Signature depends entirely on that tool, not on this integration — check its own webhook or PagerDuty-integration settings for a custom-header option.

Security

CallHeim verifies an HMAC-SHA256 signature on each source’s requests once you enable signing on that integration (the sending tool must be able to sign). The routing_key field in the body is read as an opaque identity value, not as authentication — it is not checked against anything, so do not treat it as a secret the way a PagerDuty integration key would be. The ingest URL is the actual credential.

Migration notes

Run in parallel during a move: CallHeim receives PagerDuty Events API v1 and v2 bodies, Opsgenie outgoing webhooks, and alerts forwarded from Splunk On-Call, Squadcast, Zenduty and Grafana OnCall. Every sender needs a CallHeim integration URL and key; existing PagerDuty routing keys are not reused.

Vendor documentation checked

PagerDuty: Events API v2 overview — checked 2026-09-24

The thresholds it passes through

Dedup window: 300s
Flap threshold: 4 transitions / 600s
Title correlation: similarity ≥ 0.6, same source and service
Group window default: 600s

All defaults are published. You can turn title correlation off or change its threshold, and set the window on your own noise rules; the dedup window and the flap settings are fixed. How alerts are processed →

Send PagerDuty Events API (compatible) alerts to on-call with CallHeim.