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.

pagerdutyeventssource names also accepted: pd-events, pagerduty-events, events-api, eventsv2, pdevents

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

  1. Step 1A monitoring tool's own built-in "PagerDuty" integration sends an Events API v2 (or legacy v1) body.
  2. 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.
  3. Step 3CallHeim reads dedup_key (or incident_key) as the identity signal when the sender supplies one, and maps payload.severity.
  4. 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.
  5. Step 5The integration's bound service selects an escalation policy, which pages the on-call tier.

Setting it up

  1. 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.

  2. 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.

  3. 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 payload in PagerDuty's 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 fieldMaps toNote
payload.summary / description (v1) / summaryincident title
payload.severity (critical / error / warning / info)severitycritical→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 signalOnly an explicit key populates the identity; without one, CallHeim hashes the summary and source instead.
event_action (v2) / event_type (v1): trigger / acknowledge / resolvelifecycleCallHeim 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

Common problems and how to fix them
ProblemFix
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

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 →

CallHeim

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.