Datadog Alerts to On-Call

Datadog monitor alerts become CallHeim alerts: repeats of the same monitor collapse onto one incident, and the service the monitor is bound to pages whoever is on call for it. CallHeim includes a payload mapping for Datadog’s webhook format, built and tested against sample payloads.

How the alert reaches on-call

Step 1A Datadog monitor changes state and renders your webhook payload template.
Step 2Datadog POSTs the rendered JSON body to your CallHeim ingest URL over HTTPS.
Step 3CallHeim reads alert_id plus the monitor group (alert_scope, or the group in the alert title) as the identity signal, maps priority or alert_type to a severity, and reads alert_transition to tell a recovery from a trigger.
Step 4Repeats of the same monitor group within five minutes collapse onto one incident.
Step 5The integration's bound service selects an escalation policy, which pages the on-call tier.

Setting it up

01
Create the webhook in Datadog first, with a custom payload.
Datadog's default webhook body is empty; the integration only receives usable fields when you supply a payload template yourself, in Integrations > Webhooks.
02
Name the webhook and enter your CallHeim ingest URL.
Create the Datadog integration in CallHeim first so you have the exact ingest URL to paste in.
03
Set the payload template to include alert_id, alert_title, alert_type, alert_transition, alert_scope, priority, event_msg and tags.
These are the fields the CallHeim parser reads. alert_transition is what marks a Recovered notification; alert_scope keeps each group of a multi-alert monitor separate. Omitting alert_id means repeats are grouped by title and tags instead of the monitor identity.
04
Reference the webhook from a monitor.
Add @webhook-<name> to the monitor's notification message so state changes call it.

Example payloadJSON

{
  "alert_id": "1234567",
  "alert_title": "[Triggered on {host:web-1}] High error rate on web-store",
  "alert_type": "error",
  "alert_transition": "Triggered",
  "alert_scope": "host:web-1",
  "priority": "normal",
  "event_msg": "error rate is 12% (> 5%) on service:web-store env:prod",
  "tags": "service:web-store,env:prod"
}

Example shape written by us, in the fields our template asks Datadog to send; check Datadog's own documentation for the full variable list.

What CallHeim reads from the payload

Payload fields and what each one maps to on the incident
Payload field	Maps to	Note
alert_title / title / event_title	incident title	First one present wins; falls back to "Datadog alert".
priority (P1–P5)	severity	Used only when it holds a P1–P5 value. The template's $PRIORITY is Datadog's event priority (normal or low), which does not map, so severity then comes from alert_type. Send $ALERT_PRIORITY in this field to use the monitor's own P1–P5 priority.
alert_type (error / warning / success / info / no_data)	severity	Used when priority holds no P1–P5 value: error→P1, warning→P3, success, info and no_data→P4.
event_msg / body / text_only_msg / message	incident body
alert_id + alert_scope	identity signal	The monitor plus its group, so each group of a multi-alert monitor is its own alert. When alert_scope is missing, the group is taken from the title prefix Datadog adds ("[Recovered on {host:web-1}] …"). The identity is the same for a trigger and its recovery.
alert_transition	lifecycle	Recovered resolves the alert for that monitor group; any other value is treated as a trigger.

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 Datadog, the fingerprint is keyed on alert_id plus the monitor group when your template sends alert_id (falling back to the title plus tags), so repeated firings of the same monitor group collapse and a different monitor or group never does.

Recovery

When Datadog sends a Recovered notification, CallHeim resolves the alert for that monitor group; an incident holding several groups closes when the last one recovers. This needs alert_transition in the payload template (and alert_scope for a multi-alert monitor). Checked on 26 September 2026 with webhooks in this template's format, sent by a test script rather than by a Datadog account.

Troubleshooting

Common problems and how to fix them
Problem	Fix
The alert arrives with no title or body.	Datadog's default webhook body is empty. Set a custom payload template on the webhook (see setup) before pointing a monitor at it.
A recovered monitor does not close the incident.	Check that the payload template sends alert_transition, and alert_scope for a multi-alert monitor. An incident that holds several groups stays open until the last one recovers.
HTTP 400 on send.	The payload template is not valid JSON once Datadog substitutes its variables — check for an unescaped quote inside $EVENT_MSG.
HTTP 401 once you enabled signing.	Datadog's webhook integration supports custom headers, so you can add X-ItOnCall-Signature there; confirm the shared secret in Datadog matches the one on the CallHeim integration.
Every Datadog alert lands as P3.	Neither priority nor alert_type was present in the delivered body — check the payload template was saved on the webhook, not just on the monitor.
Repeats open a second incident.	They arrived more than five minutes apart, or alert_id was missing from the template so the fallback title+tags signal changed between events.

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). Datadog's webhook configuration supports custom request headers, so you can add X-ItOnCall-Signature there if you enable signing. Until you do, the ingest URL itself is the credential — a request that reaches it with no signature is accepted.

Vendor documentation checked

Datadog: Webhooks integration — 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 Datadog alerts to on-call with CallHeim.