How to Test Datadog Webhooks

When a critical infrastructure metric spikes, Datadog triggers an alert. While Datadog has native integrations for Slack and PagerDuty, many engineering teams need to send these alerts to custom internal tools or niche incident management platforms.

To achieve this, you use Datadog Webhooks. However, unlike most platforms that send a strict, predefined JSON schema, Datadog requires you to build the JSON payload yourself using template variables. This level of customization makes testing them a critical step.

Customizing the Datadog Payload

When you configure a webhook in Datadog (under Integrations > Webhooks), you are presented with a text box for the "Payload".

You must write the JSON structure you want Datadog to send, injecting variables wrapped in dollar signs (like $EVENT_TITLE or $ALERT_ID).

A basic custom payload might look like this in the Datadog configuration:

{
  "alert_id": "$ALERT_ID",
  "title": "$EVENT_TITLE",
  "metric_value": "$EVENT_MSG",
  "priority": "$ALERT_PRIORITY",
  "dashboard_link": "$LINK"
}

Because you are manually typing JSON into a text box, it is incredibly easy to make a syntax error (like a missing comma or an unescaped quote in a variable) that results in invalid JSON being sent to your server.

Capturing the Webhook

Before pointing the Datadog webhook at your production server, you need to verify that your custom template variable syntax actually results in valid JSON when real metric data is injected into it.

Using Payloader is the fastest way to validate this:

1. Create an endpoint URL in Payloader.
2. Paste the Payloader URL into your Datadog Webhook configuration.
3. Save the integration.
4. Create a test monitor in Datadog and trigger it to fire an alert to your new @webhook-MyCustomIntegration destination.

Payloader captures the request instantly. Because Payloader parses the incoming body, it will immediately highlight if the JSON payload is malformed. If the payload is valid, Payloader will summarize the alert based on the data you mapped. You can visually confirm that $EVENT_TITLE correctly populated with "High Error Rate Detected" rather than an empty string.

Forwarding to your Local Environment

Once you confirm your Datadog payload template is generating the correct JSON structure, you need to write the application code to handle it.

Configure Payloader to forward the incoming Datadog webhooks directly to your local machine. When your test monitor fires in Datadog, the alert travels through Payloader and hits your localhost development server.

Because configuring Datadog monitors to fire on command can be tedious, Payloader's Replay feature is invaluable. Once you capture a single, perfectly formatted Datadog alert, you can hit "Replay" in Payloader to run that same alert through your local code dozens of times while you perfect your integration logic.

Authenticating the Webhook

Unlike platforms that use HMAC signatures based on the request body, Datadog relies on custom headers or URL parameters for authentication.

In the Datadog Webhook configuration, you can define custom headers. The standard approach is to generate a secure, random API key on your server and configure Datadog to send it as an Authorization: Bearer [YOUR_KEY] header.

When your server receives the POST request, it simply checks if the Authorization header matches your expected key. If it does not, your server must reject the payload to prevent unauthorized alerts from polluting your internal systems.