Receive Datadog Webhooks Locally (Test Datadog Webhooks on localhost)

You are wiring up an integration that reacts to Datadog alerts — paging a custom on-call system, opening a ticket, kicking off a remediation script — and you need to see your handler react to a real monitor alert. The problem is immediate: Datadog will only POST to a public URL, and your handler is running on localhost:8080. Datadog has no way to reach it.

The usual workarounds are painful. Deploying to staging for every code change is slow, and guessing at the JSON from the docs is doubly unreliable with Datadog, because you define the payload yourself — there is no canonical body to copy. What you want is to receive Datadog webhooks locally — real alert notifications hitting your local handler, with a URL that does not change every time you restart.

Why testing Datadog webhooks locally is tricky

A Datadog webhook is an outbound HTTP request that Datadog sends to a URL when a monitor or alert that references it triggers. Datadog sits on the public internet; your dev machine usually does not. It is behind a router, a corporate firewall, or both, with no public IP and no inbound ports open.

So you need something in the middle: a public endpoint Datadog can hit, that relays each request down to your laptop without you opening a single firewall port. That is what Webhook Relay does — and unlike a random tunnel URL, the endpoint is stable, so you configure Datadog once and never touch it again.

Step 1: Inspect the real payload with Webhook Bin

Before you write any handler code, see exactly what Datadog sends with your template. Open the free Webhook Bin — no signup — and you get an instant public URL.

1. Copy the Webhook Bin URL.
2. In Datadog, go to Integrations → Webhooks (the Webhooks integration tile).
3. Click New / Add Webhook, give it a name (for example bin), and paste the Webhook Bin URL.
4. Define a custom payload — usually JSON with $-variables, for example:

{
  "title": "$EVENT_TITLE",
  "type": "$ALERT_TYPE",
  "host": "$HOSTNAME",
  "body": "$EVENT_MSG",
  "link": "$LINK"
}

5. Save the webhook, then reference it from a monitor by adding @webhook-bin to the monitor's notification message. Use the monitor's Test Notifications button (or let it trigger) to fire it.

The captured request in Webhook Bin shows the full JSON body with the $-variables already substituted, plus the query string and every header. Because you control the template, this is the fastest way to confirm your variables resolve the way you expect before you write a line of handler code. For more on this approach, see How to test webhooks and What is a webhook.

Step 2: Forward the events to localhost with the relay agent

Once your payload looks right, route those same notifications into your local handler. Sign up for Webhook Relay, install the relay agent (CLI or Docker), and create a bucket — say datadog. The bucket gives you a stable public input endpoint.

Start forwarding to your local server:

relay forward --bucket datadog http://localhost:8080/webhook

The agent opens an outbound connection to Webhook Relay and streams every incoming request down to http://localhost:8080/webhook. Because the connection is outbound, there are no firewall ports to open and no public IP needed — this works from your laptop, behind a corporate proxy, or inside a Kubernetes cluster. Running in Docker? The same command works in the official webhookrelay/webhookrelayd image. Full details are in the localhost forwarding docs.

Now set the webhook's URL in the Datadog Webhooks integration to your Webhook Relay endpoint (or create it there from the start), trigger the monitor, and watch the alert arrive on localhost.

Datadog-specific configuration and quirks

A few Datadog details worth knowing:

• It is a notification handle, not a per-event subscription. You define the webhook once in Integrations → Webhooks, then opt monitors in by putting @webhook-<NAME> in their notification text. Different monitors can target the same webhook.
• The payload is yours to design. Leave the custom payload empty to get Datadog's default JSON, or define your own template with built-in $-variables ($EVENT_TITLE, $EVENT_MSG, $ALERT_TYPE, $HOSTNAME, $ORG_NAME, $LINK, $SNAPSHOT, and more) plus any custom variables you create in the tile.
• Custom headers and URL variables. You can add custom request headers and even use $-variables inside the URL — useful for routing or auth tokens.
• Test Notifications. When editing a monitor, Test Notifications sends a sample alert through the webhook so you can iterate without waiting for a real threshold breach.
• No provider signature. Datadog does not HMAC-sign the body, so secure the endpoint another way — see verification below.

If your local handler expects a different shape than the template produces — or you want to convert the alert into a Slack or Teams message — you can reshape it in flight with webhook transformations instead of editing the Datadog template each time.

Step 3: Verify and secure the request

Datadog does not sign its webhooks with an HMAC the way GitHub or Stripe do, so verification is something you build into the payload and headers. Two common approaches: add a custom header (or a $-variable secret) in the Datadog webhook config and reject any request missing it, or include an unguessable path segment in the webhook URL so only Datadog knows where to POST.

If you do introduce an HMAC-style shared secret of your own, validate it the same way you would any signed webhook — paste the body, secret, and computed digest into the free HMAC signature verifier to confirm your logic. For the general pattern and language-specific code, read Verify a webhook signature.

Replay and iterate

This is where local development gets fast:

• Replay from Datadog by hitting Test Notifications again, or re-triggering the monitor.
• Replay from Webhook Relay — past requests are stored on your bucket, so you can resend a captured alert without touching Datadog at all.
• Iterate on your handler by editing code and replaying the same delivery until it behaves correctly. No deploys just to test one alert path.

Because the Webhook Relay endpoint is stable, you can stop and restart the agent, reboot your machine, or come back next week — the Datadog configuration never needs to change.

Get started

1. Inspect the real payload in the free Webhook Bin — no signup needed.
2. Create a Webhook Relay account, install the agent, and run relay forward --bucket datadog http://localhost:8080/webhook.
3. Point your Datadog webhook at the stable endpoint, add @webhook-<NAME> to a monitor, trigger it, and watch the alert hit localhost.

You will be testing real Datadog alerts against your local handler in a few minutes — no deploys, no open firewall ports, and a URL you configure exactly once.