Triggering pipelines from Datadog monitors

Datadog lets you define the webhook body yourself, which is exactly what the generic source needs: a small JSON envelope naming the pipeline. You write the envelope once in the Datadog integration tile; every monitor that mentions the webhook then triggers a run.

1. Add the webhook in Datadog

Integrations → Webhooks → New Webhook.

Field	Value
Name	vectorstep
URL	https://<your-vectorstep-host>/webhook?source=generic
Payload	the template below
Custom Headers	{"Authorization": "Bearer $VECTORSTEP_TOKEN"}
Encode as form	unchecked (VectorStep expects a JSON body)

Store the token as a custom variable (VECTORSTEP_TOKEN on the same tile) and tick hide from view, rather than pasting it into the header text. Use a token with the webhook role — see Securing a deployment.

Payload template

{
  "pipeline": "datadog-triage",
  "source": "datadog",
  "event": "$ALERT_TRANSITION",
  "summary": "$ALERT_TITLE",
  "idempotency_key": "$ALERT_ID:$ALERT_SCOPE:$ALERT_TRANSITION",
  "data": {
    "monitor_id": "$ALERT_ID",
    "priority": "$ALERT_PRIORITY",
    "status": "$ALERT_STATUS",
    "metric": "$ALERT_METRIC",
    "query": "$ALERT_QUERY",
    "scope": "$ALERT_SCOPE",
    "hostname": "$HOSTNAME",
    "tags": "$TAGS",
    "link": "$LINK",
    "org": "$ORG_NAME"
  }
}

pipeline is required by the generic source and names the target pipeline explicitly, so the pipeline’s own trigger.match is never consulted. Use a different webhook (or a $TAGS[pipeline] lookup in place of the literal) if different monitors should reach different pipelines.

2. Reference it from a monitor

In the monitor’s notification message:

{{#is_alert}}@webhook-vectorstep{{/is_alert}}

Wrapping the handle in {{#is_alert}} fires it only on the alert transition. A bare @webhook-vectorstep also fires on Recovered, Warn and No Data transitions, each of which would start another run. Use {{#is_warning}}/{{#is_recovery}} blocks if you do want those.

3. Why the dedup key looks like that

idempotency_key is VectorStep’s dedup key. Two details matter:

• $ALERT_ID alone isn’t enough. It identifies the monitor. A multi-alert monitor (one per host, one per service) shares one ID across every group, so keying only on it would suppress the second host’s alert as a duplicate of the first. Appending $ALERT_SCOPE separates them.
• $ALERT_TRANSITION keeps recoveries distinct. Without it a Recovered notification would be suppressed as a repeat of the Triggered run inside the dedup window.

Omit idempotency_key entirely to disable dedup for this webhook.

4. Test it

Datadog’s webhook tile has no test button; trigger the monitor (or use Test Notifications on the monitor edit page) and check the run list in VectorStep. To test the template shape without Datadog, send it by hand with the variables filled in:

curl -X POST "https://<your-vectorstep-host>/webhook?source=generic&allow_testing=true" \
  -H "Authorization: Bearer $VECTORSTEP_WEBHOOK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"pipeline":"datadog-triage","source":"datadog","event":"Triggered",
       "summary":"[Triggered on {host:web-1}] High CPU","idempotency_key":"1234:host:web-1:Triggered",
       "data":{"priority":"P2","hostname":"web-1"}}'

allow_testing=true is only needed while the pipeline is stage: testing.

Template values are pasted in as-is

Datadog substitutes variables into the template text. A value containing a double quote or a newline — a monitor title with quotes in it, a multi-line $EVENT_MSG — can produce invalid JSON, and VectorStep rejects the request. That’s why the template above leaves out $EVENT_MSG. If runs are missing for one particular monitor, check its title first.

5. Using the data in a prompt

Everything under data lands in metadata. Include it in the context and refer to fields by name:

context_template:
  include:
    - summary
    - metadata

prompt_template: |
  Datadog monitor {{metadata.monitor_id}} ({{metadata.priority}}) fired for
  {{metadata.scope}}. Investigate {{metadata.hostname | default("the affected host")}}.

Severity isn’t a first-class field on the generic source, so priority (P1–P5) arrives in metadata, not as severity. Gate on it inside the pipeline, or send P1/P2 to a different pipeline name via a second webhook.

Investigating back in Datadog

This guide is inbound only — getting the alert into VectorStep. For the pipeline’s agent to query Datadog during the investigation (metrics, logs, monitors), give it Datadog’s own MCP server rather than building a custom integration; see MCP servers and Choosing an executor for external calls.

Reachability

Datadog calls out from the public internet, so VectorStep’s port must be reachable from there, and Datadog gives up after 15 seconds and retries only on 5xx. VectorStep returns 202 immediately and runs asynchronously, so slow pipelines don’t cause timeouts or duplicate deliveries.