> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rootly.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Datadog
> Connect Datadog to Rootly to ingest monitor alerts and capture notebooks, graphs and dashboards during incidents.
## Overview
Rootly's Datadog integration connects your monitoring stack to your incident response process. When a Datadog monitor fires, Rootly can receive the alert, route it to the right team, and automatically kick off an incident — all without manual intervention. During incidents, Rootly workflows can also pull Datadog notebooks, graph snapshots, and dashboards directly into the incident record.
## Features
Receive Datadog monitor alerts in Rootly via webhooks and route them to on-call or incident workflows.
Page a specific user, team, escalation policy, or service directly from a Datadog alert payload.
Create Datadog notebooks automatically from Rootly workflow actions during incidents.
Pull Datadog graph snapshots and dashboards into incident records via workflow actions.
## Before You Begin
Rootly recommends performing the installation with a **service account** to ensure the integration does not break if the installing user leaves the company. Ensure you are logged in as an **Admin** in Rootly.
You will need three pieces of information from Datadog:
* **Host** — your Datadog account's API hostname
* **API Key** — authenticates Rootly with your Datadog organization
* **Application Key** — grants Rootly permission to read dashboards
### Plan Requirements
* Datadog account with Admin access
* Rootly account with Owner or Admin role
## Installation
Navigate to **Configuration → Integrations** in Rootly, search for **Datadog**, and click **Setup**.
In Datadog, navigate to **Organization Settings → API Keys** and click **+ New Key**.
Name the key (for example, `Rootly Integration`) and click **Create Key**. Copy the key immediately.
The API key value is only shown once at creation. Copy it before closing the dialog — not the Key ID.
In Datadog, navigate to **Personal Settings → Security → Application Keys** and click **+ New Key**.
Name the key (for example, `Rootly Integration`), then edit its scope to include **Read** permission for **Dashboards**.
Copy the application key.
Rootly only requires `dashboard_read` scope. You can add more permissions if needed for other integrations, but this is the minimum required.
Back in the Rootly setup form, enter:
* **Host** — your Datadog API hostname. Common values:
| Region | Host |
| ------------- | ----------------------- |
| US1 (default) | `api.datadoghq.com` |
| US3 | `api.us3.datadoghq.com` |
| US5 | `api.us5.datadoghq.com` |
| EU | `api.eu.datadoghq.com` |
| Gov | `api.ddog-gov.com` |
* **API Key** — paste the API key you created
* **Application Key** — paste the application key you created
Click **Connect**.
Datadog will appear as **Connected** in your integrations list.
## Ingest Datadog Alerts
Once Datadog is connected, forward monitor alerts to Rootly via a webhook. Alerts received in Rootly can be routed to a Slack channel, used to page on-call responders, or trigger incident workflows automatically.
### Step 1: Set Up the Webhook in Datadog
In Datadog, navigate to **Integrations**, search for **Webhooks**, and click **Install**.
Switch to the **Configuration** tab and click **+ New** to add a webhook.
Fill in the following fields:
**Name** — give the webhook a descriptive name (for example, `Rootly_Alerts`)
**URL** — enter:
```text theme={null}
https://webhooks.rootly.com/webhooks/incoming/datadog_webhooks
```
**Payload** — choose based on your use case:
Use this payload for standard alerts that appear in Rootly's Alerts page without paging anyone.
```json theme={null}
{
"id": "$ID",
"body": "$EVENT_MSG",
"last_updated": "$LAST_UPDATED",
"event_type": "$EVENT_TYPE",
"title": "$EVENT_TITLE",
"alert_id": "$ALERT_ID",
"alert_metric": "$ALERT_METRIC",
"alert_priority": "$ALERT_PRIORITY",
"alert_query": "$ALERT_QUERY",
"alert_scope": "$ALERT_SCOPE",
"alert_status": "$ALERT_STATUS",
"alert_title": "$ALERT_TITLE",
"alert_transition": "$ALERT_TRANSITION",
"alert_type": "$ALERT_TYPE",
"date": "$DATE",
"org": {"id": "$ORG_ID", "name": "$ORG_NAME"}
}
```
Use this payload to page a specific user, team, escalation policy, or service when the alert fires. Replace `` and `` with your target resource.
```json theme={null}
{
"id": "$ID",
"body": "$EVENT_MSG",
"last_updated": "$LAST_UPDATED",
"event_type": "composite_monitor",
"title": "Datadog webhook alert",
"alert_id": "$ALERT_ID",
"alert_metric": "$ALERT_METRIC",
"alert_priority": "$ALERT_PRIORITY",
"alert_query": "$ALERT_QUERY",
"alert_scope": "$ALERT_SCOPE",
"alert_status": "$ALERT_STATUS",
"alert_title": "$ALERT_TITLE",
"alert_transition": "$ALERT_TRANSITION",
"alert_type": "$ALERT_TYPE",
"date": "$DATE",
"org": {"id": "$ORG_ID", "name": "$ORG_NAME"},
"rootly": {
"notification_target": {
"type": "",
"id": ""
}
}
}
```
| Field | Values |
| ------ | --------------------------------------------------------- |
| `type` | `User`, `Group`, `EscalationPolicy`, or `Service` |
| `id` | The resource ID — found by editing the resource in Rootly |
The only difference between these payloads is the `notification_target` object. Including it tells Rootly who to page when the alert is received.
Check the **Custom Headers** box and add the following, replacing the value with your Rootly webhook secret:
```json theme={null}
{
"secret": ""
}
```
To find your secret:
1. In Rootly, go to **Alerts → Sources → Datadog** and click **Configure**
2. Find the **Connection Instructions** panel on the right
3. Copy the **secret** value from the Custom Headers section
Click **Save**.
### Step 2: Attach the Webhook to a Monitor
In Datadog, navigate to **Monitors → New Monitor** and choose a monitor type, or open an existing monitor to edit it.
In the **Configure notifications and automations** section, reference your webhook using `@webhook-` syntax (for example, `@webhook-Rootly_Alerts`).
Click **Test Notifications** to confirm the alert reaches Rootly, then save the monitor.
Verify the alert appeared on the [Alerts page](https://rootly.com/account/alerts) in Rootly.
### Step 3: Build Alert Workflows in Rootly
With alerts flowing into Rootly, create a workflow that reacts to them. Alert workflows let you check alert fields, apply conditions, and trigger automated actions like creating an incident or notifying responders.
Navigate to **Workflows** in Rootly and click **Create Workflow**.
Select **Alert** as the workflow type. This workflow triggers whenever Rootly receives an alert from Datadog.
Select **Alert Created** to fire on new alerts, or **Alert Status Updated** to react when an existing alert changes.
Available triggers: **Alert Created** fires when a new alert is received. **Alert Status Updated** fires when an existing alert changes state.
Filter which alerts should trigger this workflow. Common patterns:
Add a condition where **Source is Datadog** to scope the workflow to Datadog alerts only.
Use payload field conditions to filter further — for example:
* `alert_priority` equals `P1`
* `alert_title` contains `CRITICAL`
* `alert_transition` equals `Triggered`
Use Datadog payload fields like `alert_priority`, `alert_status`, `alert_type`, and `alert_title` to build precise conditions.
Add one or more actions to execute when the workflow fires:
| Action | Use case |
| ----------------------- | ---------------------------------------------- |
| **Create Incident** | Auto-create an incident from the alert |
| **Page Rootly On-Call** | Page the responsible team or escalation policy |
| **Send Slack Message** | Notify a channel about the alert |
| **Send SMS or Email** | Alert responders directly |
You can chain multiple actions for a complete response process — for example, create an incident and then send a Slack message in the same workflow.
Name the workflow (for example, `Create Incident from Datadog P1 Alert`) and click **Create Workflow**.
### Verify the Workflow
After saving the workflow:
1. Return to Datadog and trigger a test alert from your monitor by clicking **Test Notifications**
2. Confirm the workflow activates in Rootly and performs the expected actions
3. View the run log under **Workflows → History** in Rootly
You have successfully built a Datadog alert workflow in Rootly!
## Workflow Actions
| Action | Description |
| ------------------------------ | -------------------------------------------------------------------------------------------- |
| **Create Datadog Notebook** | Creates a new notebook in your Datadog account, optionally pre-populated with incident data |
| **Get Datadog Graph Snapshot** | Retrieves a point-in-time snapshot of a Datadog metric graph and attaches it to the incident |
| **Get Datadog Dashboard** | Fetches a Datadog dashboard URL and surfaces it in the incident timeline |
### Create Datadog Notebook
Use this action to automatically create a Datadog notebook when an incident starts or reaches a specific status. Notebooks are useful for capturing investigation notes, timelines, and graphs in a single Datadog-native view.
Navigate to **Workflows** in Rootly and click **Create Workflow**, or open an existing workflow to edit it.
Click **Add Action**, search for **Datadog**, and select **Create Datadog Notebook**.
| Field | Required | Description |
| ----------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Name** | No | A label for this action step. Does not affect behavior. |
| **Notebook Name** | Yes | The title of the notebook. Supports Liquid syntax — use the [Liquid Variable Explorer](https://rootly.com/account/help/liquid-explorer) to build dynamic names. |
Click **Add**, name the workflow, and click **Create Workflow**.
### Get Datadog Graph Snapshot
Use this action to capture a point-in-time graph from Datadog and attach it to the incident. This is useful for preserving the state of a metric at the time an incident was declared or escalated.
In your workflow, click **Add Action**, search for **Datadog**, and select **Get Datadog Graph Snapshot**.
| Field | Required | Description |
| ---------------- | -------- | ------------------------------------------------------------------------------------------------------- |
| **Metric Query** | Yes | The Datadog metric query to snapshot — for example `avg:system.cpu.user` with an optional scope filter. |
| **Start** | No | Snapshot start time in Unix epoch seconds. Supports Liquid syntax. |
| **End** | No | Snapshot end time in Unix epoch seconds. Defaults to the current time if blank. |
### Get Datadog Dashboard
Use this action to retrieve a Datadog dashboard and surface its URL in the incident timeline. This gives responders quick access to the relevant monitoring view without leaving Rootly.
In your workflow, click **Add Action**, search for **Datadog**, and select **Get Datadog Dashboard**.
| Field | Required | Description |
| ---------------- | -------- | -------------------------------------------------------------------------------------------------- |
| **Dashboard ID** | Yes | The ID of the Datadog dashboard to fetch. Found in the dashboard URL (for example, `abc-123-xyz`). |
### Alert Workflow Patterns
In addition to incident workflow actions, you can build **Alert workflows** in Rootly that trigger automatically when a Datadog alert arrives. These are separate from incident workflows and configured under **Workflows → Alert**.
Common patterns:
* **Auto-create an incident** when a SEV-1 Datadog alert fires
* **Page on-call** for alerts with `alert_priority` of `P1` or `P2`
* **Send a Slack message** to a channel when a monitor transitions to `ALERT`
* **Resolve the alert** automatically when Datadog sends a `RECOVERY` transition
To scope workflows to Datadog only, add a condition where **Source is Datadog**, or filter on payload fields like `alert_priority`, `alert_title`, or `alert_transition`.
## Uninstall
To remove the Datadog integration:
1. Go to **Configuration → Integrations** and find **Datadog**
2. Click the **Connected** button to reveal the disconnect option
3. Click **Delete**
## Frequently Asked Questions
Verify the webhook URL is exactly `https://webhooks.rootly.com/webhooks/incoming/datadog_webhooks`. Confirm the Custom Headers `secret` value matches what is shown in **Alerts → Sources → Datadog → Configure** in Rootly. Check that the Datadog integration is still connected under **Configuration → Integrations**.
Open the resource (User, Team, Escalation Policy, or Service) in Rootly and click **Edit**. The resource ID appears in the URL or in the edit form. Copy it and paste it into the `id` field of the paging payload.
Yes. Create one webhook and attach it to as many monitors as needed by adding `@webhook-` to each monitor's notification body. Each alert will appear separately in Rootly's Alerts page.
Alert workflows in Rootly support **Alert Created** (fires on new alerts) and **Alert Status Updated** (fires when an existing alert changes). Use conditions to filter by source (Datadog), payload fields like `alert_priority` or `alert_title`, or alert status.
By default, Rootly only pages for CRITICAL alerts from Datadog. WARNING vs. CRITICAL is the monitor's `alert_status` field in the webhook payload — not `alert_priority` (which is your monitor's P1–P5 importance and is independent of state). To extend paging to WARNING alerts, either configure your monitor to fire on the threshold you want treated as paging-eligible, or build an alert workflow that matches `alert_status` equals `Warn` (or `Warning`, depending on the value Datadog sends) and routes to the same target as CRITICAL.
### Workflow Questions
Check the workflow run log in Rootly for error details. Confirm the Datadog Application Key has sufficient permissions and that the integration is still connected under **Configuration → Integrations**.
Yes. Datadog actions can be combined with any other Rootly workflow actions in the same workflow — for example, create a Datadog notebook and then send a Slack message with the notebook link.
Any incident Liquid variable is supported. Use the [Liquid Variable Explorer](https://rootly.com/account/help/liquid-explorer) to browse available variables and preview their values.
## Related Resources
* [Alert workflows](/workflows/alert-workflows)
* [Alert routing](/alerts/alert-routing)
* [Integrations overview](/integrations/overview)