Incident & ITSM
Send PagerDuty Events API alerts to on-call with CallHeim.
Accepts PagerDuty Events API v2 and legacy v1 request bodies at your CallHeim URL, for tools that let you set the Events API endpoint. CallHeim maps the payload, attaches repeats to the incident that is already open, and pages whoever is on call for the service it belongs to.
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 the Events API request format.
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 URL identifies the integration, so the routing key in the body is not used to find it.
- 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 and generate its routing key.
This gives you the ingest URL for the integration. Choose Generate routing key to get a CallHeim routing key (it starts ik_) as well; a PagerDuty-shaped event posted to the bare CallHeim endpoint, without the integration URL, needs it.
- 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. If the tool requires a routing key value, enter the CallHeim routing key in place of the PagerDuty one; existing PagerDuty keys are not reused.
- 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.
{
"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 }
}
}What CallHeim reads from the payload
| 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 | CallHeim reads this field directly for state. Resolve and acknowledge act on the open incident and never open one. |
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
A repeat of the same alert attaches to the incident that is still open for it in the same service, triggered or acknowledged, with no new incident and no new page. When the sender supplies its own dedup key (a PagerDuty dedup_key, an Opsgenie alias, a Datadog alert id, an Alertmanager fingerprint, or a dedupKey that is more than the alert title), this holds however late the repeat arrives. When the identity comes from the e-mail subject or the alert title, the repeat attaches only if the incident was triggered in the last 24 hours; after that it opens a new incident and pages. A repeat at P1 or P2 is not folded into an open P3, P4 or P5 incident: it opens a new incident and pages. Once an incident is resolved or closed, the next repeat 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. A supplied key attaches at any age; the summary-and-source fallback is a derived identity, so the 24-hour limit applies to it.
Recovery
An event_action (or the legacy event_type) of resolve with the same dedup_key closes the alert at P4, and acknowledge is recognized as a state change too. Checked with a test script that posts PagerDuty's Events API v2 body shape, rather than with traffic sent by PagerDuty.
Troubleshooting
| 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 earlier incident had already been resolved, or 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, and with that fallback an open incident triggered more than 24 hours ago no longer absorbs repeats. |
| 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 sign depends on that tool, not on this integration. A fixed custom header cannot carry the per-request X-CallHeim-Signature value, so leave signing off unless a proxy you run signs each request. |
Security
Use the CallHeim integration URL. It identifies the integration, so the routing_key (v2) or service_key (v1) in the body is ignored. A PagerDuty-shaped event posted to the bare CallHeim endpoint, without the integration URL, needs the CallHeim routing key instead, and an event with an unknown key gets a PagerDuty-style invalid-event reply. Whether a sending tool can sign depends on that tool. The integration URL is the credential: keep it secret, and if it is exposed, disable the integration and create a new one. A signing proxy you run in front of the sender can add an X-CallHeim-Signature header; without one, do not set a signing secret, because every unsigned delivery would be rejected.
Migration notes
Run in parallel during a move: CallHeim receives PagerDuty Events API v1 and v2 requests and Opsgenie outgoing webhooks, and alerts forwarded from Splunk On-Call, Squadcast (now SolarWinds Incident Response), Zenduty (now Xurrent IMR) and Grafana OnCall. Every sender needs its own CallHeim integration URL; existing PagerDuty routing keys are not reused.
Vendor documentation checked
- PagerDuty: Events API v2 overview — checked 2026-09-24
The thresholds it passes through
- Repeat, sender-supplied dedup key
- attaches, any age
- Repeat, title or subject only
- attaches, incident under 24 h old
- 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 rule and the flap settings are fixed. A P1 or P2 repeat on an open P3 to P5 incident opens a new incident and pages. How alerts are processed →
Point PagerDuty Events API at CallHeim and see what it does with your alerts.
Start on the free trial, connect PagerDuty Events API and send a test alert to see the incident it opens.