Datadog destination
Beta
Data Destinations is currently available as a Private Beta product and the information contained in this document is subject to change. Data Destinations is not a HIPAA Eligible Service or PCI compliant and should not be enabled in workflows that are subject to HIPAA or PCI. To learn more, see Private beta legal information.
Datadog provides monitoring and analytics for cloud infrastructure and applications, letting you turn Twilio events into Datadog events for real-time visibility and alerting.
- Category: Analytics, Performance monitoring
- Release status: Beta
- Authentication: API key
- Regional availability: US1
Get early access to native destinations for data warehouses, observability tools, and event pipelines.
You can send all event types supported by Event Streams to Datadog. This destination has no user-identifier restriction.
Before you set up a Datadog destination, make sure you have:
- A Datadog account.
- Your Datadog API Key, found in your Datadog account settings.
- Your Datadog Application Key, found in your Datadog account settings.
Info
See Set up a destination for the full UI and Destinations API setup flow common to every destination type.
To create a Datadog destination in the Twilio Console:
- From your Datadog account, gather the settings listed in Destination settings.
- In the Twilio Console, go to Data > Data Destinations > Destinations > Add destination subscription.
- Complete the Add destination subscription wizard.
To create a Datadog destination through the Destinations API, send a POST request to the Destinations endpoint and set destinationType to datadog. For authentication and the other request body fields, see Create a destination.
POST "https://destinations.twilio.com/v1/ControlPlane/Destinations"
Set the config object in the request body as follows:
| Name | Type | Description |
|---|---|---|
credentials.credentialType (Required) | string | Set to API_KEY. |
credentials.ddApiKey (Required) | string | Your Datadog API key. |
credentials.ddApplicationKey (Required) | string | Your Datadog Application key. |
site | enum<string> | Your Datadog site. API keys are scoped to a specific regional site. The default is US1. Valid values: US1, US3, US5, EU1, AP1, US1-FED. |
The following example shows a request body. Replace the uppercase placeholder values with your own.
1{2"destinationType": "datadog",3"name": "My Datadog destination",4"config": {5"credentials": {6"credentialType": "API_KEY",7"ddApiKey": "DD_API_KEY",8"ddApplicationKey": "DD_APPLICATION_KEY"9}10}11}
Use datadog as the destinationType.
| Field | Description | Required | Default or choices |
|---|---|---|---|
| API Key | Your Datadog API key. Sensitive: entered once and stored encrypted. | Yes | N/A |
| Application Key | Your Datadog Application key. Sensitive: entered once and stored encrypted. | Yes | N/A |
| Site | Your Datadog site. API keys are scoped to a specific regional site. | No | US1 (default); US3, US5, EU1, AP1, US1-FED |
Twilio authenticates to Datadog by using your API Key and Application Key, which Twilio sends as request headers on every event delivered to Datadog.
| Field | Datadog field |
|---|---|
| Event type | Title |
| Event time | Timestamp |
| Event source / account | Tags |
| Event payload | Custom attributes |
ok (constant) | Alert Status |
When you save a Datadog destination, Twilio validates your API Key against Datadog before marking the destination active. This check doesn't verify your Application Key. An incorrect Application Key passes validation and causes delivery failures only after Twilio starts sending events. If validation fails, check that:
- Your API Key is correct and hasn't been revoked in Datadog.
- The Site you selected matches the region your Datadog account is actually hosted in.
Twilio doesn't currently offer a way to manually trigger a test event for this destination, from either the Console or the CLI. To confirm delivery works, wait for a real event of a subscribed type to occur.
| Cause | What you'll see | Fix |
|---|---|---|
| Invalid or revoked API Key | Validation fails with an auth error | Re-check the API Key in Datadog and update the destination |
| Invalid or revoked Application Key | Passes validation, then delivery errors reported in the Debugger | Re-check the Application Key in Datadog and update the destination |
| Wrong Site selected | Validation fails even with correct keys | Confirm your account's region in Datadog and update site |
| Datadog rejects the event payload (400), for example, null custom attributes | Delivery fails, not retried; reported in the Debugger | Check your subscription's mapping for invalid custom attributes |
| Datadog rate-limiting requests (429), or a transient server error (5xx) | Delivery fails, retried automatically; reported in the Debugger | Retry is automatic. Sustained errors may indicate you've exceeded the Datadog rate limit, so check the Datadog status page |
If Twilio can't deliver events to your destination, Twilio sends an error notification to the Debugger (available in US1 region only). If Twilio continues to encounter delivery errors, Twilio notifies you every 20 minutes after the initial error.