Datadog webhooks: @webhook mentions, custom payloads and retries

A Datadog webhook is a POST request that the Webhooks integration sends to your URL whenever a monitor mentioning @webhook-<WEBHOOK_NAME> notifies. The quickest way to run a Datadog webhook test and see what Datadog sends is to register a free bin URL and run Test Notifications on a monitor. There's no signup, and the bin lasts 48 hours and takes 100 requests a day. Here we'll cover setup, the default payload, custom payloads and variables, headers and auth, and retries.

Send a Datadog test notification to a bin

1. Create a free bin in your browser at view.webhooks.page or from the terminal with curl -X POST https://webhooks.sh/v1/bins, which returns JSON with your ingest_url and view_url.
2. Open the Datadog Webhooks integration tile and add a webhook with a name (say bin) and the bin's ingest URL (https://<bin>.webhooks.page/), or create it with the POST https://api.datadoghq.com/api/v1/integration/webhooks/configuration/webhooks API call below.
3. Add @webhook-bin to the text of a monitor's message.
4. Select Test Notifications at the bottom right of the monitor page, pick the monitor transition to test (only states your alert conditions define are offered), and select Run Test. The request shows up live in the viewer, with [TEST] in the notification title.

# 1. Create a free bin (or open view.webhooks.page)
curl -X POST https://webhooks.sh/v1/bins

# 2. Register it as a webhook named "bin" (or use the tile)
DD=https://api.datadoghq.com/api/v1/integration
curl -X POST "$DD/webhooks/configuration/webhooks" \
  -H "Authorization: Bearer $DD_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"bin","url":"https://<bin>.webhooks.page/dd"}'

# 3. Put @webhook-bin in a monitor message, then
#    select Test Notifications > Run Test

See the default payload for yourself

Datadog's Webhooks integration page says a monitor mention sends a POST request with JSON content, but it doesn't show an example of the default payload body. That's the gap a bin fills: run a test notification against it and you see every header and field your account sends, before you write a parser.

If you'd rather control the fields yourself, set your own Payload (covered in the next section). Leave the Payload field empty in the tile to keep the default; if you create the webhook through the API, setting payload to null uses the default payload.

Custom payloads with template variables

When you write your own JSON in the Payload field, Datadog fills in the $ template variables when it sends the notification. If your receiver expects form data instead, tick Encode as form (or set encode_as to form in the API) and keep writing the payload in JSON format; Datadog sends it URL-encoded.

Watch out for one quirk on Logs Monitor alerts: $ALERT_STATUS isn't populated unless you add it manually in the Webhooks integration tile. You can also define your own custom variables in the tile to reuse across webhook URLs, payloads, and custom headers, and tick hide from view if the values shouldn't stay visible in the UI. Send a test notification to your bin after each edit to check how the variables render.

{
  "title": "$EVENT_TITLE",
  "transition": "$ALERT_TRANSITION",
  "monitor_id": "$ALERT_ID",
  "status": "$ALERT_STATUS",
  "date_ms": "$DATE",
  "link": "$LINK",
  "tags": "$TAGS",
  "env": "$TAGS[env]"
}

Custom headers and authentication

Custom headers in the tile have to be valid JSON, like {"X-Source": "datadog"} (or pass custom_headers in the API, where null sends no extra headers). For Basic authentication, put the credentials straight into the webhook URL as https://<USERNAME>:<PASSWORD>@my.service.example.com. For OAuth 2.0, create an Auth Method with your Access Token URL, Client ID, and Client Secret (Scope and Audience are optional), and Datadog will request a token with grant_type client_credentials, refresh it when needed, and attach it to the webhook request as a Bearer token.

One thing to know when you inspect these in a bin: Basic and Bearer credentials travel in the Authorization header, which the bin redacts in the viewer and API, and any custom header whose name contains key, token, secret, or cookie shows as redacted too. Use a harmless test value in a non-redacted header name while you debug.

Timeout, retries and queues

Datadog only retries a webhook when there's an internal error (a badly formed notification message) or when your endpoint returns a 5XX response. Each individual request times out after 15 seconds, and missed connections are retried 5 times. When a single monitor alert notifies 2 or more webhook endpoints, Datadog keeps a separate queue per service, so a slow retry on one endpoint won't hold up notifications going to the others.

A webhooks.sh bin answers 200 with {"ok":true,"delivery_id":"..."} right away, so one notification shows up once. The catch is the free tier limits: after 100 requests in a day, a free bin refuses new requests with 429 daily_cap_reached (and bodies over 100KB get 413 body_too_large), and because 429 isn't a 5XX, Datadog won't retry it and that notification never reaches the bin. If a test alert doesn't show up at all, see troubleshooting a webhook not received.

Keep the bin or move to your own receiver

A free bin expires after 48 hours and the viewer only shows the latest 10 requests. If you need the URL to stick around while you finish building your receiver, claim the bin from the bin page with a free Google sign-in before it expires: the https://<bin>.webhooks.page/ URL stays the same, new requests are kept for 30 days on a rolling basis, and the limits stay at 100 requests a day and 100KB bodies.

If you're routing alerts into a local dev server or want a permanent endpoint, Solo ($12 a month) gives you named, persistent endpoints on webhooks.host with 250,000 requests per billing period and bodies up to 5MB. It also includes the wsh CLI to relay live notifications to your machine (wsh listen <endpoint> --to localhost:3000) and can forward every request to up to 3 of your own verified HTTPS URLs.

FAQ

How do I test a Datadog webhook?

Add a free bin URL in the Datadog Webhooks integration tile, put @webhook-<WEBHOOK_NAME> in a monitor message, and select Test Notifications at the bottom right of the monitor page. The request shows up live in your browser with no signup required.

What does the default Datadog webhook payload look like?

Datadog's Webhooks documentation doesn't show an example of the default payload body. Send a test notification to a bin with the Payload field left empty to capture the exact JSON your account sends, or write your own JSON payload using $ variables like $ALERT_TITLE and $EVENT_MSG.

How do I trigger a Datadog webhook from a monitor?

Add @webhook-<WEBHOOK_NAME> to the text of the monitor's message, matching the name you gave the webhook in the integration tile. Whenever the monitor notifies, Datadog sends a POST request to that webhook's URL.

Does Datadog retry failed webhooks?

Datadog only retries after an internal error (a badly formed notification message) or when the receiving URL returns a 5XX status code. Each request has a 15-second timeout, and missed connections are retried 5 times.

How do I add authentication to a Datadog webhook?

Put Basic auth credentials directly in the URL (https://<USERNAME>:<PASSWORD>@my.service.example.com), configure an OAuth 2.0 Auth Method so Datadog sends a Bearer token, or pass custom headers in JSON format.

Can a Datadog webhook send form data instead of JSON?

Yes. Tick Encode as form in the Webhooks integration tile (or set encode_as to form in the API) and write your payload in JSON format; Datadog will send the request URL-encoded.