From d859822e0c9ceb0a6d94e2f09c50063a67bed8ed Mon Sep 17 00:00:00 2001 From: Apu Emdad Date: Tue, 13 Oct 2026 23:32:24 +0600 Subject: [PATCH 1/2] docs(integrations): rewrite the Datadog page as a webhook alert-source guide The page described dashboard links from services, which no longer exist. Rewrite it after grafana.md around what OpsiMate does with Datadog today: receiving monitor alerts at POST /api/v1/alerts/custom/datadog. Cover the webhook URL (and the X-API-Token header), setting up the webhook with the in-app custom payload, attaching it to monitors, how the payload is read, auto-resolve on Recovered, tag parsing, severity from tags or priority, and that the Configure form isn't needed for ingestion. Change the front-matter tags to [Alerts] and keep the official resources. Closes OpsiMate/OpsiMate#1091 --- opsimate-docs/docs/integrations/datadog.md | 112 ++++++++++++++++++--- 1 file changed, 98 insertions(+), 14 deletions(-) diff --git a/opsimate-docs/docs/integrations/datadog.md b/opsimate-docs/docs/integrations/datadog.md index 3623003..027aa2d 100644 --- a/opsimate-docs/docs/integrations/datadog.md +++ b/opsimate-docs/docs/integrations/datadog.md @@ -1,29 +1,112 @@ --- sidebar_position: 5 -tags: [Links, Monitoring Data] +tags: [Alerts] --- # DataDog Integration -**DataDog** is a monitoring and analytics platform for cloud-scale applications, providing monitoring of servers, databases, tools, and services through a SaaS-based data analytics platform. +The **Datadog integration** lets Datadog push monitor alerts to OpsiMate with a Datadog **Webhook**. -**Integration Capabilities:** -- 🔗 **Links**: Direct access to DataDog dashboards and metrics from services +OpsiMate does not poll Datadog for alerts, and Datadog alert ingestion does not require a Datadog API key. -## Configuration Parameters +## Webhook URL -Required credentials to connect to DataDog: +Configure your Datadog webhook to send alerts to your OpsiMate server: -- **DataDog Site**: Your DataDog site (e.g., `us5.datadoghq.com` for US, `datadoghq.eu` for EU) -- **API Key**: Your DataDog API key for authentication -- **Application Key**: (Optional) Required for certain API operations +```text +http://:3001/api/v1/alerts/custom/datadog?api_token={your_api_token} +``` -## Functionality +Replace `{your_api_token}` with the API token configured in your OpsiMate server. -### Dashboard Links -- Access DataDog dashboards directly from OpsiMate services -- View service-specific metrics and logs in DataDog -- Quick navigation to related dashboards and monitors +Instead of the `api_token` query parameter, you can send the token in an `X-API-Token` header. In the Datadog webhook, add it under **Custom headers**: + +```json +{ + "X-API-Token": "{your_api_token}" +} +``` + +## API Token Configuration + +The API token used in the webhook URL is managed by OpsiMate through an environment variable: + +- **Env var**: `API_TOKEN` +- **Default value**: `opsimate` + +If you are using the **simple deployment** (via the provided `docker-compose.yml`), the `API_TOKEN` environment variable is already defined there for you. + +Make sure your OpsiMate server is started with `API_TOKEN` set (or rely on the default), and use the same value in the Datadog webhook. + +## Setting Up the Webhook in Datadog + +1. In Datadog, go to **Integrations > Webhooks**. +2. Click **New** to create a new webhook. +3. Give the webhook a name, for example `opsimate-alerts`. +4. Paste the webhook URL above into the **URL** field. +5. Set the **Payload** to this custom payload: + + ```json + { + "alert_id": "$ALERT_ID", + "id": "$ID", + "title": "$EVENT_TITLE", + "message": "$EVENT_MSG", + "alert_status": "$ALERT_STATUS", + "alert_transition": "$ALERT_TRANSITION", + "event_type": "$EVENT_TYPE", + "link": "$LINK", + "tags": "$TAGS", + "alert_scope": "$ALERT_SCOPE", + "date": "$DATE", + "last_updated": "$LAST_UPDATED", + "org": { + "id": "$ORG_ID", + "name": "$ORG_NAME" + } + } + ``` + +6. If you want priority-based severity (see [Severity](#severity)), also add `"priority": "$PRIORITY"` to the payload. +7. Save the webhook. + +## Attaching the Webhook to Monitors + +1. Open the Datadog monitor you want in OpsiMate. +2. In the monitor's **Notify** section, add `@webhook-opsimate-alerts` (or `@webhook-` followed by the name you chose). +3. Save the monitor and trigger a test notification to check that the alert shows up in OpsiMate. + +## How the Payload Is Read + +- `id`, `title` and `date` are required. A body without them is rejected with HTTP 400. +- `id` identifies the alert. A later notification with the same `id` updates that alert. +- `title` becomes the alert name and `message` becomes the summary. +- `link` becomes a **View in Datadog** link on the alert. + +### Auto-Resolve + +When `alert_transition` contains `Recovered`, OpsiMate resolves the alert with the same `id`. + +### Tags + +Every `key:value` entry in `$TAGS` becomes an alert tag. Entries without exactly one `:` are skipped. + +### Severity + +- A `severity:critical` (or `severity:warning` / `severity:info`) tag on the monitor wins. +- Otherwise the monitor's priority is used: P1 → critical, P2–P3 → warning, P4–P5 → info. +- Unknown or missing values → warning. + +## The Configure Form + +The Datadog card on the **Integrations** page still has a form with the Datadog URL, API key and Application key. Alert ingestion does not need these: the webhook above is all OpsiMate needs to receive Datadog alerts. + +## Important Disclaimer + +Datadog sends webhooks only to HTTP endpoints it can reach. + +- Datadog runs in the cloud, so it cannot call `localhost` on your OpsiMate server directly. +- Deploy OpsiMate behind a reachable URL, reverse proxy, or secure tunnel so Datadog can reach the webhook endpoint. ## Official Resources @@ -31,3 +114,4 @@ Required credentials to connect to DataDog: - **Documentation**: [https://docs.datadoghq.com/](https://docs.datadoghq.com/) - **API Documentation**: [https://docs.datadoghq.com/api/](https://docs.datadoghq.com/) - **Getting Started**: [https://docs.datadoghq.com/getting_started/](https://docs.datadoghq.com/getting_started/) +- **Webhooks integration**: [https://docs.datadoghq.com/integrations/webhooks/](https://docs.datadoghq.com/integrations/webhooks/) From c49414d2874d0629568b85f04f5af8682c3b0888 Mon Sep 17 00:00:00 2001 From: idanlodzki Date: Wed, 14 Oct 2026 00:13:33 +0300 Subject: [PATCH 2/2] docs(integrations): fix Datadog webhook id and priority variables - Use $ALERT_CYCLE_KEY for "id": $ID is a new event ID per notification, so recoveries never matched the triggering alert - Use $ALERT_PRIORITY (monitor priority P1-P5) instead of $PRIORITY (event priority normal/low) for severity - Point the API Documentation link at https://docs.datadoghq.com/api/ - Spell Datadog consistently in the title and resources Co-Authored-By: Claude Opus 5.5 --- opsimate-docs/docs/integrations/datadog.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/opsimate-docs/docs/integrations/datadog.md b/opsimate-docs/docs/integrations/datadog.md index 027aa2d..51cc542 100644 --- a/opsimate-docs/docs/integrations/datadog.md +++ b/opsimate-docs/docs/integrations/datadog.md @@ -3,7 +3,7 @@ sidebar_position: 5 tags: [Alerts] --- -# DataDog Integration +# Datadog Integration The **Datadog integration** lets Datadog push monitor alerts to OpsiMate with a Datadog **Webhook**. @@ -49,7 +49,7 @@ Make sure your OpsiMate server is started with `API_TOKEN` set (or rely on the d ```json { "alert_id": "$ALERT_ID", - "id": "$ID", + "id": "$ALERT_CYCLE_KEY", "title": "$EVENT_TITLE", "message": "$EVENT_MSG", "alert_status": "$ALERT_STATUS", @@ -67,7 +67,7 @@ Make sure your OpsiMate server is started with `API_TOKEN` set (or rely on the d } ``` -6. If you want priority-based severity (see [Severity](#severity)), also add `"priority": "$PRIORITY"` to the payload. +6. If you want priority-based severity (see [Severity](#severity)), also add `"priority": "$ALERT_PRIORITY"` to the payload. Use `$ALERT_PRIORITY` (the monitor priority, P1–P5), not `$PRIORITY`, which is the event priority (`normal` / `low`). 7. Save the webhook. ## Attaching the Webhook to Monitors @@ -79,7 +79,7 @@ Make sure your OpsiMate server is started with `API_TOKEN` set (or rely on the d ## How the Payload Is Read - `id`, `title` and `date` are required. A body without them is rejected with HTTP 400. -- `id` identifies the alert. A later notification with the same `id` updates that alert. +- `id` identifies the alert. A later notification with the same `id` updates that alert. `$ALERT_CYCLE_KEY` stays the same from the time an alert triggers until it resolves, so the recovery notification matches the original alert. Don't use `$ID` here: it is a new event ID on every notification, so recoveries would never resolve the alert. - `title` becomes the alert name and `message` becomes the summary. - `link` becomes a **View in Datadog** link on the alert. @@ -94,7 +94,7 @@ Every `key:value` entry in `$TAGS` becomes an alert tag. Entries without exactly ### Severity - A `severity:critical` (or `severity:warning` / `severity:info`) tag on the monitor wins. -- Otherwise the monitor's priority is used: P1 → critical, P2–P3 → warning, P4–P5 → info. +- Otherwise the monitor's priority (`$ALERT_PRIORITY`) is used: P1 → critical, P2–P3 → warning, P4–P5 → info. - Unknown or missing values → warning. ## The Configure Form @@ -110,8 +110,8 @@ Datadog sends webhooks only to HTTP endpoints it can reach. ## Official Resources -- **DataDog Website**: [https://www.datadoghq.com/](https://www.datadoghq.com/) +- **Datadog Website**: [https://www.datadoghq.com/](https://www.datadoghq.com/) - **Documentation**: [https://docs.datadoghq.com/](https://docs.datadoghq.com/) -- **API Documentation**: [https://docs.datadoghq.com/api/](https://docs.datadoghq.com/) +- **API Documentation**: [https://docs.datadoghq.com/api/](https://docs.datadoghq.com/api/) - **Getting Started**: [https://docs.datadoghq.com/getting_started/](https://docs.datadoghq.com/getting_started/) - **Webhooks integration**: [https://docs.datadoghq.com/integrations/webhooks/](https://docs.datadoghq.com/integrations/webhooks/)