---
"@context": https://schema.org
"@type": TechArticle
"@id": https://www.twilio.com/docs/data-destinations/destination/azure-events#article
headline: Azure Event Hubs destination
description: Learn how to send event data to Azure Event Hubs for real-time stream processing and analytics.
url: https://www.twilio.com/docs/data-destinations/destination/azure-events
inLanguage: en
dateModified: 2026-11-04T17:24:28.000Z
author:
  "@type": Organization
  name: Twilio Developer Education Team
publisher:
  "@type": Organization
  name: Twilio
---

# Azure Event Hubs destination

> \[!IMPORTANT]
>
> 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](/docs/data-destinations#private-beta-legal-information).

[Azure Event Hubs](https://azure.microsoft.com/products/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.

### Destination overview

* **Category**: Raw data
* **Release status**: Beta
* **Authentication**: SAS key or OAuth 2.0
* **Regional availability**: US1

## Join the Data Destinations private beta

[Sign up](https://airtable.com/appaJfyV6LiIFMxuP/pagIaOAtKsQVxTfdW/form)

Get early access to native destinations for data warehouses, observability tools, and event pipelines.

## Eligible events

You can send all [event types](/docs/events/event-types-overview) supported by Event
Streams to Azure Event Hubs. This destination has no user-identifier
restriction.

## Get started

### Prerequisites

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.

## Create the destination

> \[!NOTE]
>
> See [Set up a destination](/docs/data-destinations/destination-setup) for the
> full UI and Destinations API setup flow common to every destination type.

### Twilio Console

To create an Azure Event Hubs destination in the Twilio Console:

1. From your Azure account, gather the settings listed in [Destination settings](#destination-settings).
2. In the Twilio Console, go to **Data** > **Data Destinations** > **Destinations** > **Add destination subscription**.
3. Complete the **Add destination subscription** wizard.

### Destinations API

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](/docs/data-destinations/api-quickstart#create-a-destination).

```text title="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` <br />(**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` <br />(**Required**)                   | string | Name of the event hub (topic) to publish to. Must exist before events can be sent.                        |
| `namespace` <br />(**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:

```json title="Example request body"
{
  "destinationType": "azure-events",
  "name": "My Azure Event Hubs destination",
  "config": {
    "credentials": {
      "credentialType": "SAS",
      "sasKey": "SAS_KEY",
      "sasKeyName": "SAS_KEY_NAME"
    },
    "eventHub": "EVENT_HUB",
    "namespace": "NAMESPACE"
  }
}
```

With `OAUTH2` credentials:

```json title="Example request body"
{
  "destinationType": "azure-events",
  "name": "My Azure Event Hubs destination",
  "config": {
    "credentials": {
      "credentialType": "OAUTH2",
      "clientId": "CLIENT_ID",
      "clientSecret": "CLIENT_SECRET",
      "tenantId": "TENANT_ID"
    },
    "eventHub": "EVENT_HUB",
    "namespace": "NAMESPACE"
  }
}
```

## Destination settings

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.

## Default mappings

| 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` |

## Verification and troubleshooting

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](/docs/usage/troubleshooting/debugging-your-application).
* 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.

### Common errors

| 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](/docs/usage/troubleshooting/debugging-your-application) | 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](/docs/usage/troubleshooting/debugging-your-application) | 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](/docs/usage/troubleshooting/debugging-your-application) (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](/docs/usage/troubleshooting/debugging-your-application) (available in US1 region only). If Twilio continues to encounter delivery errors, Twilio notifies you every 20 minutes after the initial error.

## Additional resources

* [Destinations overview](/docs/data-destinations/destinations-overview)
* [Set up a destination](/docs/data-destinations/destination-setup)
* [Event types reference](/docs/events/event-types-overview)