Skip to main content
datadog icon

Datadog Connector

Sourcenpm · v0.2.0API DocsConnector Changelog

Description​

Datadog is a monitoring and analytics platform for cloud-scale infrastructure, applications, and logs. This component allows submitting metrics, managing webhook integrations, and receiving monitor alert notifications from Datadog.

API Documentation​

This component was built using the Datadog API Reference utilizing the v2 Metrics API for submitting metrics and the v1 Metrics and Webhooks Integration APIs for listing and searching metrics and managing webhooks.

Connections​

API Key + Application Key​

key: apiKey

Prerequisites​

To configure this connection, the following are required:

  • A Datadog account with appropriate permissions
  • A Datadog API Key (created under Organization Settings > API Keys)
  • A Datadog Application Key (created under Organization Settings > Application Keys)

Setup Steps​

  1. Log in to the Datadog account.
  2. Navigate to Organization Settings > API Keys.
  3. Click + New Key to create an API Key. Copy the key value.
  4. Navigate to Organization Settings > Application Keys.
  5. Click + New Key to create an Application Key. Copy the key value.
  6. Note the Datadog site/region (e.g., US1, EU, US3).

Configure the Connection​

Create a connection of type API Key + Application Key and enter:

FieldDescription
Datadog SiteSelect the Datadog site that matches the organization (US1, US3, US5, EU, AP1, AP2, or US1-FED).
API KeyThe Datadog API Key. Identifies the organization.
Application KeyThe Datadog Application Key. Authorizes management and read operations.
InputNotesExample
API Key

The Datadog API Key. Create one at Organization Settings > API Keys in Datadog.

a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
Application Key

The Datadog Application Key. Required for management and read endpoints. Create one at Organization Settings > Application Keys in Datadog.

a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0
Datadog Site

Select the Datadog site that matches the organization. This determines the API base URL.

https://api.datadoghq.com

OAuth 2.0 Authorization Code​

key: oauth2

Prerequisites​

To configure this connection, the following are required:

  • A Datadog account with organization admin permissions
  • A registered OAuth application with Datadog (typically for marketplace/partner integrations)
  • The Client ID and Client Secret from the OAuth application

Setup Steps​

  1. Register the application with Datadog as an integration partner.
  2. Obtain the Client ID and Client Secret from the Datadog Developer Platform.
  3. Enter the OAuth callback URL https://oauth2.prismatic.io/callback as the Redirect URI of the OAuth application.
  4. Configure the required OAuth scopes for the use case (e.g., metrics_read, create_webhooks).
  5. Note the Datadog site/region (e.g., US1, EU, US3).

Configure the Connection​

Create a connection of type OAuth 2.0 Authorization Code and enter:

FieldDescription
Datadog SiteSelect the Datadog site that matches the organization.
Client IDThe Client ID from the Datadog OAuth application.
Client SecretThe Client Secret from the Datadog OAuth application.

The Authorize URL and Token URL are pre-configured for the standard Datadog OAuth endpoints. The connection requests the scopes metrics_read, timeseries_query, metric_tags_manage, and create_webhooks by default.

InputNotesExample
Authorize URL

The Datadog OAuth 2.0 authorization endpoint.

https://app.datadoghq.com/oauth2/v1/authorize
Client ID

The Client ID from the Datadog OAuth application.

Client Secret

The Client Secret from the Datadog OAuth application.

Datadog Site

Select the Datadog site that matches the organization. This determines the API base URL.

https://api.datadoghq.com
Revoke URL

The Datadog OAuth 2.0 token revocation endpoint.

https://api.datadoghq.com/oauth2/v1/revoke
Scopes

Space-separated OAuth 2.0 scopes. Available scopes include: metrics_read, timeseries_query, metric_tags_manage, create_webhooks.

metrics_read timeseries_query metric_tags_manage create_webhooks
Token URL

The Datadog OAuth 2.0 token endpoint.

https://api.datadoghq.com/oauth2/v1/token

Triggers​

Alert Notification Events​

Receive Datadog monitor alert notifications via webhook. Automatically registers a webhook in Datadog on deploy and removes it on delete. | key: webhook

InputNotesExample
Connection

The Datadog connection to use for authentication.

Custom Headers

Custom headers to attach to webhook requests as a JSON string. Useful for authentication headers.

{"Authorization": "Bearer my-token"}
Webhook Name

The name of the webhook. Used in Datadog monitor notifications as @webhook-NAME.

my-integration-webhook
Payload

Custom JSON payload for the webhook. If not provided, uses the default Datadog payload with standard variables like $ALERT_TITLE, $ALERT_STATUS, etc.

{"title": "$ALERT_TITLE", "status": "$ALERT_STATUS"}

The Webhook trigger receives alert notifications from Datadog monitors. When a monitor changes state (e.g., from OK to Alert), Datadog sends an HTTP POST to the configured webhook URL with details about the alert.

How It Works​

  1. On Instance Deploy: The trigger creates a webhook integration in Datadog pointing to the flow's webhook URL. If a webhook with the same name already points to that URL, the trigger updates it instead. If the Webhook Name changed since the last deploy, the trigger removes the webhook registered under the old name.
  2. Monitor Configuration: Configure Datadog monitors to notify @webhook-<name> where <name> matches the Webhook Name configured in the trigger.
  3. On Alert: When a monitor triggers, Datadog sends the alert payload to the webhook URL.
  4. On Instance Deletion: The trigger removes the webhook integration from Datadog.

The same create and remove steps run when entering and leaving Listening Mode in the integration designer, using a temporary webhook URL.

Event Types​

Alert Transitions (8)
Alert TransitionDescription
TriggeredMonitor threshold exceeded, alert fires
Re-TriggeredRepeated Triggered notification
RecoveredMonitor returned to normal state
RenotifyOngoing alert re-notification
No DataMonitor reports no data received
Re-No DataRepeated No Data notification
WarnMonitor entered warning state
Re-WarnRepeated Warn notification

Refer to Datadog's monitor notification documentation for details on configuring monitor alerts.

Returned Data​

Example Payload
{
  "ALERT_ID": "12345678",
  "ALERT_METRIC": "system.load.1",
  "ALERT_QUERY": "avg(last_5m):avg:system.load.1{host:my-host} > 5",
  "ALERT_SCOPE": "host:my-host",
  "ALERT_STATUS": "Triggered",
  "ALERT_TITLE": "CPU load is high on my-host",
  "ALERT_TRANSITION": "Triggered",
  "ALERT_TYPE": "metric alert",
  "DATE": "2024-01-15 10:30:00 UTC",
  "HOSTNAME": "my-host",
  "LINK": "https://app.datadoghq.com/monitors/12345678",
  "ORG_NAME": "My Organization",
  "TAGS": "environment:production,region:us-east-1"
}

Notes​

  • The Webhook Name must be unique within the Datadog organization. Datadog identifies webhooks by name, so the trigger only updates or removes a webhook that points to the flow's webhook URL. Deploying with a name already used by a webhook that points elsewhere fails with an error asking for a unique Webhook Name, and that webhook is left unchanged.
  • After deploying, add @webhook-<name> to the monitor's notification message in Datadog.
  • Custom payloads can use Datadog template variables like $ALERT_TITLE, $HOSTNAME, $TAGS, etc.
  • Datadog does not document any request signing for webhooks, so the trigger cannot verify that a request came from Datadog. Treat the webhook URL as a secret. The trigger does not check any header or credential on incoming requests: headers set in Custom Headers, and OAuth 2.0 authentication from Datadog's Webhooks integration, are sent by Datadog but do not stop other callers from using the URL unless a later step in the flow validates them.
Example Payload for Alert Notification Events⤓
Loading…

Data Sources​

Select Metric​

A searchable picklist of metric names in the Datadog account. | key: selectMetric | type: picklist

InputNotesExample
Connection

The Datadog connection to use for authentication.

Example Payload for Select Metric⤓
Loading…

Actions​

Create Webhook​

Create a new webhook integration endpoint in Datadog. The webhook can then be referenced in monitor notifications as @webhook-NAME. | key: createWebhook

InputNotesExample
Connection

The Datadog connection to use for authentication.

Custom Headers

Custom headers to attach to webhook requests as a JSON string. Useful for authentication headers.

{"Authorization": "Bearer my-token"}
Encode As

Encoding type for the webhook payload. Defaults to "json".

Webhook Name

The name of the webhook. Used in Datadog monitor notifications as @webhook-NAME.

my-integration-webhook
Payload

Custom JSON payload for the webhook. If not provided, uses the default Datadog payload with standard variables like $ALERT_TITLE, $ALERT_STATUS, etc.

{"title": "$ALERT_TITLE", "status": "$ALERT_STATUS"}
Webhook URL

The URL of the webhook endpoint that will receive the data.

https://hooks.example.com/datadog
Example Payload for Create Webhook⤓
Loading…

Delete Webhook​

Delete a Datadog webhook integration by name. This action cannot be undone. | key: deleteWebhook

InputNotesExample
Connection

The Datadog connection to use for authentication.

Webhook Name

The name of the webhook. Used in Datadog monitor notifications as @webhook-NAME.

my-integration-webhook
Example Payload for Delete Webhook⤓
Loading…

Get Webhook​

Retrieve the configuration of a specific Datadog webhook integration by name. | key: getWebhook

InputNotesExample
Connection

The Datadog connection to use for authentication.

Webhook Name

The name of the webhook. Used in Datadog monitor notifications as @webhook-NAME.

my-integration-webhook
Example Payload for Get Webhook⤓
Loading…

List Metrics​

List active metric names that have reported data since a given timestamp, with optional host and tag filtering. | key: listMetrics

InputNotesExample
Connection

The Datadog connection to use for authentication.

From

Unix timestamp (seconds) from which to list active metrics. Metrics reported after this time are returned.

1636629071
Host

Hostname to filter the list of active metrics. Only metrics reported by this host are returned.

my-host
Tag Filter

Filter metrics by tag. Supports boolean expressions (e.g., "env:production AND role:web").

env:production
Example Payload for List Metrics⤓
Loading…

Raw Request​

Send a raw HTTP request to any Datadog API endpoint. | key: rawRequest

InputNotesExample
Connection

The Datadog connection to use for authentication.

Data

The HTTP body payload to send to the URL.

{"exampleKey": "Example Data"}
Debug Request

Enabling this flag will log out the current request.

false
File Data

File Data to be sent as a multipart form upload.

[{key: "example.txt", value: "My File Contents"}]
File Data File Names

File names to apply to the file data inputs. Keys must match the file data keys above.

Form Data

The Form Data to be sent as a multipart form upload.

[{"key": "Example Key", "value": new Buffer("Hello World")}]
Header

A list of headers to send with the request.

User-Agent: curl/7.64.1
Max Retry Count

The maximum number of retries to attempt. Specify 0 for no retries.

0
Method

The HTTP method to use.

Query Parameter

A list of query parameters to send with the request. This is the portion at the end of the URL similar to ?key1=value1&key2=value2.

Response Type

The type of data you expect in the response. You can request json, text, or binary data.

json
Retry On All Errors

If true, retries on all erroneous responses regardless of type. This is helpful when retrying after HTTP 429 or other 3xx or 4xx errors. Otherwise, only retries on HTTP 5xx and network errors.

false
Retry Delay (ms)

The delay in milliseconds between retries. This is used when 'Use Exponential Backoff' is disabled.

0
Timeout

The maximum time that a client will await a response to its request

2000
URL

The URL path to send the request to. The base URL is determined by the Datadog Site configured in the connection. For example, to call the Submit Metrics endpoint, enter /api/v2/series.

/api/v2/series
Use Exponential Backoff

Specifies whether to use a pre-defined exponential backoff strategy for retries. When enabled, 'Retry Delay (ms)' is ignored.

false

Search Metrics​

Search for Datadog metrics by name prefix. Returns matching metric names. | key: searchMetrics

InputNotesExample
Connection

The Datadog connection to use for authentication.

Query

Search query to find metrics by name prefix. The "metrics:" prefix is added automatically.

system.cpu
Example Payload for Search Metrics⤓
Loading…

Submit Metrics​

Submit time-series metric data to Datadog for graphing on dashboards. Uses the v2 API endpoint. | key: submitMetrics

InputNotesExample
Connection

The Datadog connection to use for authentication.

Metric Series

JSON array of metric series to submit. Each series must include "metric" (name) and "points" (array of {timestamp, value}). Optional fields: type, interval, unit, tags, resources.

[
  {
    "metric": "system.load.1",
    "type": 3,
    "points": [
      {
        "timestamp": 1636629071,
        "value": 0.7
      }
    ],
    "resources": [
      {
        "name": "dummyhost",
        "type": "host"
      }
    ],
    "tags": [
      "environment:production"
    ]
  }
]
Example Payload for Submit Metrics⤓
Loading…

Submit Single Metric​

Submit a single metric data point to Datadog. For bulk submissions, use the Submit Metrics action. | key: submitSingleMetric

InputNotesExample
Connection

The Datadog connection to use for authentication.

Metric Fields

Optional metric configuration and resource details.

Metric Name

The name of the timeseries metric (e.g., system.load.1, custom.my_metric).

system.load.1
Tags

Tags associated with the metric. Each tag is a string in "key:value" format.

environment:production
Timestamp

Unix timestamp in seconds. Defaults to the current time if not provided. Must be within 10 minutes in the future or 1 hour in the past.

1636629071
Value

The numeric value for the metric data point (64-bit float).

0.7
Example Payload for Submit Single Metric⤓
Loading…

Update Webhook​

Update the configuration of an existing Datadog webhook integration. | key: updateWebhook

InputNotesExample
Connection

The Datadog connection to use for authentication.

Custom Headers

Custom headers to attach to webhook requests as a JSON string. Useful for authentication headers.

{"Authorization": "Bearer my-token"}
Encode As

Encoding type for the webhook payload. Defaults to "json".

Webhook Name

The name of the webhook. Used in Datadog monitor notifications as @webhook-NAME.

my-integration-webhook
Payload

Custom JSON payload for the webhook. If not provided, uses the default Datadog payload with standard variables like $ALERT_TITLE, $ALERT_STATUS, etc.

{"title": "$ALERT_TITLE", "status": "$ALERT_STATUS"}
Webhook URL

The URL of the webhook endpoint that will receive the data.

https://hooks.example.com/datadog
Example Payload for Update Webhook⤓
Loading…

Changelog​

2026-11-05​

Updated to the latest spectral

2026-11-04​

Published the component as an npm package, so code-native integrations can install it and call its actions, triggers and data sources from code with TypeScript types

2026-10-21​

Fixed credential logging in Debug Mode and improved metric and webhook input handling and request validation:

  • Fixed Debug Mode printing the API key, application key, and OAuth access token in request headers in the logs; Debug Mode no longer logs request details on any action, including Raw Request, so credentials are no longer logged
  • Updated the Alert Notification Events trigger to register its Datadog webhook idempotently: a deploy updates a webhook of the same name that already points to the flow, creates it when absent, and fails with an error asking for a unique Webhook Name when that name belongs to a webhook pointing elsewhere; deleting the trigger or leaving Listening Mode removes the webhook only if it points to the flow, and renaming the Webhook Name removes the webhook registered under the old name
  • Fixed Submit Single Metric submitting a data point of 0 when Value was left blank; a blank Value now fails with "Value is required and must be a number."
  • Fixed Update Webhook sending an empty URL when Webhook URL was left blank; a blank Webhook URL is now omitted from the request, so the webhook keeps its existing URL
  • Updated List Metrics to reject a blank From; a blank From previously listed metrics from the epoch and now fails with "From is required and must be a number."
  • Updated Submit Metrics to validate Metric Series; malformed JSON or a value that is not an array now fails with a clear message instead of an opaque API error
  • Updated Submit Single Metric to omit the resource entry from the request when neither Resource Name nor Resource Type is set
  • Added an output schema to the Delete Webhook action for improved field mapping during configuration

2026-08-12​

Fixed webhook alert delivery and improved input and action configuration:

  • Fixed the Alert Notification Events trigger to register its Datadog webhook against the deployed flow's own URL, so alert notifications are now delivered in flows with any name
  • Grouped the optional metric configuration and resource inputs on Submit Single Metric into a Metric Fields structured object; Tags remains a top-level input
  • Added inline action calling support across all actions so the app builder can show example output during configuration
  • Added output schemas to actions for improved field mapping

2026-04-30​

Updated spectral version

2026-03-06​

Initial release of the Datadog component with support for submitting metrics, managing webhook integrations, and receiving monitor alert notifications via the Alert Notification Events trigger