Azure Event Hubs 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.
Azure Event Hubs is a fully managed, real-time data ingestion service. Sending event data to Azure Event Hubs lets you stream communications events into your Azure-based pipelines for real-time processing and analytics.
- Category: Raw data
- Release status: Beta
- Authentication: SAS key or OAuth 2.0
- 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 Azure Event Hubs. This destination has no user-identifier restriction.
Before you set up an Azure Event Hubs destination, make sure you have:
- An Azure account with an Event Hubs namespace and an event hub already created. Twilio delivers to an existing event hub and doesn't create one for you.
- Credentials for one of the two supported authentication methods:
- Shared Access Signature (SAS): a SAS Key Name and SAS Key, found under your Event Hubs namespace's Shared access policies in the Azure portal.
- Microsoft Entra ID (OAuth 2.0 client credentials): a Tenant ID, Client ID, and Client Secret from an Entra ID app registration that has been granted the Azure Event Hubs Data Sender role on your namespace.
- Your Event Hubs Namespace name (the short name, not the full hostname) and Event Hub name.
Info
See Set up a destination for the full UI and Destinations API setup flow common to every destination type.
To create an Azure Event Hubs destination in the Twilio Console:
- From your Azure 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 an Azure Event Hubs destination through the Destinations API, send a POST request to the Destinations endpoint and set destinationType to azure-events. 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 SAS or OAUTH2, depending on your authentication method. |
credentials.sasKey | string | Your SAS primary or secondary key value. Required when credentialType is SAS. |
credentials.sasKeyName | string | Your SAS policy name, for example RootManageSharedAccessKey. Required when credentialType is SAS. |
credentials.clientId | string | Your Azure AD application (client) ID (GUID). Required when credentialType is OAUTH2. |
credentials.clientSecret | string | Your Azure AD client secret value. Required when credentialType is OAUTH2. |
credentials.tenantId | string | Your Azure AD tenant ID (GUID) or verified tenant domain. Required when credentialType is OAUTH2. |
eventHub (Required) | string | Name of the event hub (topic) to publish to. Must exist before events can be sent. |
namespace (Required) | string | Your short Event Hubs namespace name, for example mynamespace. Don't include .servicebus.windows.net. |
The following examples show each authentication method. Replace the uppercase placeholder values with your own.
With SAS credentials:
1{2"destinationType": "azure-events",3"name": "My Azure Event Hubs destination",4"config": {5"credentials": {6"credentialType": "SAS",7"sasKey": "SAS_KEY",8"sasKeyName": "SAS_KEY_NAME"9},10"eventHub": "EVENT_HUB",11"namespace": "NAMESPACE"12}13}
With OAUTH2 credentials:
1{2"destinationType": "azure-events",3"name": "My Azure Event Hubs destination",4"config": {5"credentials": {6"credentialType": "OAUTH2",7"clientId": "CLIENT_ID",8"clientSecret": "CLIENT_SECRET",9"tenantId": "TENANT_ID"10},11"eventHub": "EVENT_HUB",12"namespace": "NAMESPACE"13}14}
Use azure-events as the destinationType.
| Field | Description | Required | Default or choices |
|---|---|---|---|
| Namespace | Short Event Hubs namespace name (for example, mynamespace). Don't include .servicebus.windows.net. | Yes | N/A |
| Event Hub | Name of the event hub (topic) to publish to. Must already exist. | Yes | N/A |
| SAS Key Name | SAS policy name (for example, RootManageSharedAccessKey). Used with the SAS authentication method. | Yes (SAS method) | N/A |
| SAS Key | SAS primary or secondary key value. Sensitive, stored encrypted. | Yes (SAS method) | N/A |
| Tenant ID | Azure AD tenant ID (GUID). Used with the Microsoft Entra ID authentication method. | Yes (Entra ID method) | N/A |
| Client ID | Azure AD application (client) ID (GUID). | Yes (Entra ID method) | N/A |
| Client Secret | Azure AD client secret value. Sensitive, stored encrypted. | Yes (Entra ID method) | N/A |
Twilio supports two authentication methods for Azure Event Hubs. Pick the one that fits your organization:
- Shared Access Signature (SAS): a namespace-scoped Send policy key. Quick to set up, but the key itself doesn't expire automatically, so plan to rotate it periodically by using your namespace's primary/secondary key pair for zero-downtime rotation.
- Microsoft Entra ID (OAuth 2.0 client credentials): an Entra ID application granted the Azure Event Hubs Data Sender role. This is the method Microsoft recommends because it uses short-lived tokens and integrates with your organization's identity and access policies. Required if your namespace has turned off SAS-based local authentication.
| Field | Azure Event Hubs field |
|---|---|
| Event payload | Message body |
| Event type | User property: eventType |
| Event ID | User property: eventId |
| Event time | User property: eventTime |
| Event source | User property: eventSource |
When you save an Azure Event Hubs destination, Twilio validates your credentials before marking the destination active:
- With Microsoft Entra ID credentials, Twilio validates by exchanging them for an access token. No data is written during validation. This confirms your Tenant ID, Client ID, and Client Secret are valid, but it does not confirm the app registration has the Azure Event Hubs Data Sender role, or that the Namespace/Event Hub names are correct. A missing role or wrong name will pass validation and only surface later, as a delivery failure reported in the Debugger.
- With SAS credentials, Twilio sends a small test event to your event hub, since a Send-scoped SAS token can only be validated by publishing. This does confirm the SAS policy has Send rights and that the Namespace and Event Hub names are correct, since publishing the test event exercises all three.
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 is working, wait for a real event of a subscribed type to fire.
| Cause | What you'll see | Fix |
|---|---|---|
| Invalid or expired SAS key / client secret | Validation fails with an auth error | Re-check your credentials and update the destination |
| SAS policy missing Send rights | Validation fails with a 401/403 | Grant Send rights to the policy in the Azure portal and retry |
| Entra ID app missing the Data Sender role | Passes validation, then delivery errors reported in the Debugger | Grant the Azure Event Hubs Data Sender role to the app registration |
| Namespace or event hub name incorrect (SAS) | Validation fails | Confirm the namespace (short name only) and event hub name |
| Namespace or event hub name incorrect (Entra ID) | Passes validation, then delivery errors reported in the Debugger | Confirm the namespace (short name only) and event hub name |
| Event Hubs namespace under-provisioned for your event volume (throughput units exhausted) | Delivery errors reported in the Debugger (503) | Increase throughput units or turn on auto-inflate on your namespace |
If Twilio can't deliver events to your event hub, 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.