# Send events to Azure Event Grid

Consume Stripe events in your Azure infrastructure.

> This feature is currently in public preview.

[Azure Event Grid](https://learn.microsoft.com/en-us/azure/event-grid/overview) is a scalable, fully managed event routing service provided by Microsoft Azure. By integrating with Event Grid using an event destination, you can route Stripe events directly to your Azure infrastructure without needing to manage integration code or infrastructure scaling logic. When Event Grid receives events, it can route them to [various event handlers](https://learn.microsoft.com/en-us/azure/event-grid/event-handlers)—including [webhooks](https://learn.microsoft.com/en-us/azure/event-grid/handler-webhooks), [Azure functions](https://learn.microsoft.com/en-us/azure/event-grid/handler-functions), or [Event Hub](https://learn.microsoft.com/en-us/azure/event-grid/handler-event-hubs)—to process or trigger business automations.

## Event flow from Stripe to Event Grid

Stripe generates events when activities occur in your account. These events are sent to Event Grid through an [Azure partner topic](https://learn.microsoft.com/en-us/azure/event-grid/concepts#partner-topics) in your [Azure subscription](https://learn.microsoft.com/en-us/microsoft-365/enterprise/subscriptions-licenses-accounts-and-tenants-for-microsoft-cloud-offerings?view=o365-worldwide) (defined as an event destination on Stripe). Then, [Azure event subscriptions](https://learn.microsoft.com/en-us/azure/event-grid/subscribe-through-portal) route these events to your configured [event handlers](https://learn.microsoft.com/en-us/azure/event-grid/event-handlers), which process the data according to your business logic.

## Register the Event Grid resource provider [Azure portal]

Before you can use Event Grid, you’ll need to register the Event Grid [resource provider](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/resource-providers-and-types) in your [subscription](https://learn.microsoft.com/en-us/microsoft-365/enterprise/subscriptions-licenses-accounts-and-tenants-for-microsoft-cloud-offerings?view=o365-worldwide). If you’ve used Event Grid before in your subscription, skip to the next section to create a partner authorization.

To register the Event Grid resource provider In the Azure portal:

1. Use the search bar to select **Subscriptions**.
1. Select the subscription you want to use for Event Grid from the subscription list.
1. On the **Subscription** page, click **Settings** > **Resource providers**.
1. Search for **Microsoft.EventGrid**, and confirm that the **Status** is **Not Registered**. If the status is **Registered**, skip to the next section and create a partner authorization.
1. Select **Microsoft.EventGrid** in the provider list.
1. Select **Register** on the command bar.
1. Refresh to make sure the status of **Microsoft.EventGrid** is changed to **Registered**.

## Create a partner authorization [Azure portal]

Create a [partner authorization](https://learn.microsoft.com/en-us/azure/event-grid/subscribe-to-partner-events#authorize-partner-to-create-a-partner-topic) in the Azure portal so Stripe has consent to create a [partner topic](https://learn.microsoft.com/en-us/azure/event-grid/concepts#partner-topics) in the [subscription](https://learn.microsoft.com/en-us/microsoft-365/enterprise/subscriptions-licenses-accounts-and-tenants-for-microsoft-cloud-offerings?view=o365-worldwide) and [resource group](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/overview#resource-groups) you designate.

1. Sign in to the Azure portal.
1. In the search bar at the top, enter **Partner Configurations**, and select **Event Grid Partner Configurations** under **Services** in the results.
1. On the **Event Grid Partner Configurations** page, select **Create Event Grid partner configuration** button on the page or **+ Create** on the command bar.
1. On the **Create Partner Configuration** page, do the following steps:
1. In the **Project Details** section, select the subscription and the resource group where you want to allow the partner to create a partner topic.
1. In the **Partner Authorizations** section, specify a default expiration time for partner authorizations defined in this configuration.
1. To provide your authorization for a partner to create partner topics in the specified resource group, select the **+ Partner Authorization** link.
1. Select **Review + create**.
1. On the **Add partner authorization to create resources** page, follow these steps to authorize Stripe:
1. Select **Stripe** from the list of [verified partners](https://learn.microsoft.com/en-us/azure/event-grid/partner-events-overview#verified-partners)
1. Specify **authorization expiration time**. When configuring an Event Grid integration, you’ll set an authorization expiration period that determines how long Stripe can create new partner topics in the subscription. This authorization is used whenever a new Stripe event destination is created with this subscription ID. We recommend setting this to 90 days for most implementations. This expiration affects Stripe’s ability to create new partner topics in the subscription. Existing partner topics and event delivery will continue to function even after the authorization expires.
1. Select **Add**.
1. Go to the **Create Partner Configuration** page, then verify that the partner is added to the partner authorization list at the bottom.
1. Select **Review + create** at the bottom of the page.
1. On the **Review** page, review all settings, and then select **Create** to create the partner registration.

## Add a new event destination [Workbench]

> #### Send events in your sandbox
> 
> Use your live account or [sandboxes](https://docs.stripe.com/sandboxes.md) to send events to Event Grid.

Create an event destination using Workbench in the Dashboard or programmatically with the [API](https://docs.stripe.com/api/v2/core/event-destinations.md).

#### Dashboard

To create an event destination in the Dashboard:

1. Open the [Webhooks](https://dashboard.stripe.com/workbench/webhooks) tab in Workbench.
1. Click **Create new destination**.
1. Select where you want to receive events from. Stripe supports two types of configurations: **Your account** and [Connected accounts](https://docs.stripe.com/connect.md). Select **Account** to listen to events from your own account. If you created a [Connect application](https://docs.stripe.com/connect.md) and want to listen to events from your connected accounts, select **Connected accounts**.

> #### Listen to events from an Organization event destination
> 
> If you create an event destination in an [Organization](https://docs.stripe.com/get-started/account/orgs.md), select **Accounts** to listen to events from accounts in your organization or select **Connected and v2 accounts** to listen to events from your connected and v2 accounts in your organization.

1. Select the [event types](https://docs.stripe.com/api/events/types.md) that you want this destination to receive. Then, click **Continue**.
1. Select **Azure Event Grid** as your destination type, then click **Continue**.
1. Enter the following information: 
   - [Azure subscription ID](https://learn.microsoft.com/en-us/microsoft-365/enterprise/subscriptions-licenses-accounts-and-tenants-for-microsoft-cloud-offerings?view=o365-worldwide): The subscription where your Stripe partner topic is created to receive events.
   - [Azure resource group](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/overview#resource-groups): The resource group that will contain the Stripe partner topic.
   - [Azure region](https://aws.amazon.com/about-aws/global-infrastructure/regions_az/): The regions where the Stripe partner topic will be deployed.
   - (Optional) **Destination name**: A unique name of this event destination resource in Stripe. If you don’t provide one, we generate a random name for you. You can change it later.
   - (Optional) **Description**: A description that distinguishes your event destination instance. You can modify this later.
1. Click **Create destination**.

#### API

Use the [API](https://docs.stripe.com/api/v2/event-destinations.md) to create a new event destination for Event Grid. In the example below, Stripe notifies you when a [usage-based billing](https://docs.stripe.com/billing/subscriptions/usage-based.md) validation error is triggered.

If you’ve created a [Connect application](https://docs.stripe.com/connect.md) and want to listen to your connected accounts, use the [events_from](https://docs.stripe.com/api/v2/core/event-destinations/create.md#v2_create_event_destinations-events_from) parameter and set its value to `@accounts`. For [Organization](https://docs.stripe.com/get-started/account/orgs.md) event destinations, use `@organization_members` for events from accounts in your organization, or `@organization_members/@accounts` for events from connected accounts across your organization.

## Activate the partner topic [Azure portal]

After you set up an event destination, Stripe creates a [partner topic](https://learn.microsoft.com/en-us/azure/event-grid/partner-events-overview-for-partners#customers-authorization-to-create-partner-topics) in the subscription and region you provided during configuration. You need to activate the partner topic to allow Stripe to send events to the partner topic. Activate the partner topic within 7 days of the event destination’s creation. If you don’t associate it within this time frame, Azure automatically deletes the partner topic. After a partner topic is deleted, your Stripe event destination is automatically disabled and you must create a new destination to receive events.

1. In the search bar of the Azure portal, search for and select **Event Grid Partner Topics**.
1. On the **Event Grid Partner Topics** page, select the Stripe partner topic. For live mode destinations, the partner topic name is identical to your event destination ID (which begins with “ed_”). For sandbox destinations, the partner topic name is your event destination ID with the “test_” prefix removed. You can find your event destination ID in the **Webhooks** tab of Stripe’s **Workbench** by viewing the details of your Event Grid destination.
1. Review the activation message, and select **Activate** on the page or on the command bar to activate the partner topic before the expiration time mentioned on the page.
1. Confirm that the activation status is set to **Activated**.

## Create event subscriptions and event handlers [Azure Portal]

After activating your Stripe partner topic, you must create at least one [event subscription](https://learn.microsoft.com/en-us/azure/event-grid/subscribe-through-portal) with an [event handler](https://learn.microsoft.com/en-us/azure/event-grid/event-handlers) to receive your Stripe events. An event subscription defines which events from Stripe partner topics are routed to specific event handlers. Without these components, events will be sent to Event Grid and persisted for 24 hours. However, they won’t be delivered to any destination.

You can repeat these steps multiple times to define multiple event subscriptions and event handlers:

1. In your Azure subscription, set up a service that’s [supported as an event handler in Event Grid](https://docs.microsoft.com/en-us/azure/event-grid/event-handlers). This handler processes the events that Stripe sends to your partner topic. For example, you can use the [Event Grid Viewer](https://learn.microsoft.com/en-us/azure/event-grid/custom-event-quickstart-portal#create-a-message-endpoint) sample, which deploys a [prebuilt web app](https://github.com/Azure-Samples/azure-event-grid-viewer) that displays the Stripe event messages received from the partner topic.
1. In the Azure portal, type **Event Grid Partner Topics** in the search box, and select **Event Grid Partner Topics**.
1. On the **Event Grid Partner Topics** page, select the Stripe partner topic in the list. For live mode destinations, the partner topic name is identical to your event destination ID (which begins with “ed_”). For sandbox destinations, the partner topic name is your event destination ID with the “test_” prefix removed. You can find your event destination ID in the **Webhooks** tab of Stripe’s **Workbench** by viewing the details of your Event Grid destination.
1. On the **Event Grid Partner Topic** page for the partner topic, select **+ Event Subscription** on the command bar.
1. On the **Create Event Subscription** page, do the following steps:
1. Enter a **name** for the event subscription.
1. For **Filter to Event Types**, select types of events that your subscription receives.
1. For **Endpoint Type**, select the Azure service you used as your event handler.
1. Select the **Configure an endpoint link**.
1. On the **Select Event Hub** page, select configurations for the endpoint, and then select **Confirm Selection**.
1. On the **Create Event Subscription** page, select **Create**.

Your Stripe events are now successfully delivered to your partner topic and its corresponding event handlers.

## Trigger test events

To send test events, trigger an event type that your event destination is subscribed to by manually creating an object in the Stripe Dashboard. Learn how to trigger events with [Stripe for VS Code](https://docs.stripe.com/stripe-vscode.md).

#### Trigger a snapshot event

You can use the following command in either [Stripe Shell](https://docs.stripe.com/workbench/shell.md) or [Stripe CLI](https://docs.stripe.com/stripe-cli.md). This example triggers a `payment_intent.succeeded` event:

```bash
stripe trigger payment_intent.succeeded
Running fixture for: payment_intent
Trigger succeeded! Check dashboard for event details.
```

#### Trigger a thin event

You can use the following command in the [Stripe CLI](https://docs.stripe.com/stripe-cli.md). This example triggers a `v1.billing.meter.error_report_triggered` event:

```bash
stripe trigger v1.billing.meter.error_report_triggered
Setting up fixture for: list_billing_meters
Running fixture for: list_billing_meters
Setting up fixture for: billing_meter
Running fixture for: billing_meter
Setting up fixture for: list_billing_meters_after_creation
Running fixture for: list_billing_meters_after_creation
Setting up fixture for: billing_meter_event_session
Running fixture for: billing_meter_event_session
Setting up fixture for: create_billing_meter_event_stream
Running fixture for: create_billing_meter_event_stream
Trigger succeeded! Check dashboard for event details.
```

## Event delivery behaviors

This section helps you understand different behaviors to expect regarding how Stripe sends events to Azure Event Grid.

### Automatic retries

Stripe attempts to deliver events to your destination for up to three days with an exponential back off in live mode. View when the next retry will occur, if applicable, in your event destination’s **Event deliveries** tab. We retry event deliveries created in a sandbox three times over the course of a few hours. If your destination has been disabled or deleted when we attempt a retry, we prevent future retries of that event. However, if you disable and then re-enable the event destination before we’re able to retry, you still see future retry attempts.

### Manual retries

You can’t manually resend events to Azure Event Grid.

### Event ordering

Stripe doesn’t guarantee the delivery of events in the order that they’re generated. For example, creating a subscription might generate the following events:

- `customer.subscription.created`
- `invoice.created`
- `invoice.paid`
- `charge.created` (if there’s a charge)

Make sure that your event destination isn’t dependent on receiving events in a specific order. Be prepared to manage their delivery appropriately. You can also use the API to retrieve any missing objects. For example, you can retrieve the invoice, charge, and subscription objects with the information from `invoice.paid` if you receive this event first.

### API versioning

The API version in your account settings when the event occurs dictates the API version, and therefore the structure of an [Event](https://docs.stripe.com/api/events.md) sent to your destination. For example, if your account is set to an older API version, such as 2015-02-16, and you change the API version for a specific request with [versioning](https://docs.stripe.com/api.md#versioning), the [Event](https://docs.stripe.com/api/events.md) object generated and sent to your destination is still based on the 2015-02-16 API version. You can’t change [Event](https://docs.stripe.com/api/events.md) objects after creation. For example, if you update a charge, the original charge event remains unchanged. As a result, subsequent updates to your account’s API version don’t retroactively alter existing [Event](https://docs.stripe.com/api/events.md) objects. Retrieving an older [Event](https://docs.stripe.com/api/events.md) by calling `/v1/events` using a newer API version also has no impact on the structure of the received event. You can set test event destinations to either your default API version or the latest API version. The [Event](https://docs.stripe.com/api/events.md) sent to the destination is structured for the event destination’s specified version.

## Event destination status

Event Grid destinations have several statuses that describe their readiness to receive events:

- **Active**: Stripe is sending events to Event Grid if you have activated the partner topic in Azure.
- **Disabled**: Stripe isn’t sending events to Event Grid. Your destination is in this status either because you manually disabled it or Stripe automatically disabled it due to an expired partner topic activation.

## Event structure

Event Grid delivers events using the CloudEvents schema (`v1.0`), which is an open specification for standardizing event data interchange. When you receive Stripe events through Event Grid, the original Stripe event JSON object will be wrapped in the `data` property within the CloudEvents envelope.

Here’s an example of a `v1.billing.meter.error_report_triggered` event delivered through Event Grid:

```json
{
  "specversion": "1.0",			
  "type": "v1.billing.meter.error_report_triggered",			
  "source": "/providers/stripe/ed_test_61StH5LQO42M712JD16Sr8c00mSQTEEmwCfiQq4wqQc4",
  "id": "9aeb0fdf-c01e-0131-0922-9eb54906e209",	
  "time": "2025-07-11T14:30:00Z",
  "subject": null,
  "dataContentType": "application/cloudevents+json",
  "data": {
    {
      "id": "evt_test_65R9Ijk8dKEYZcXeRWn16R9A7j1FSQ3w3TGDPLLGSM4CW0",
      "object": "v2.core.event",
      "type": "v1.billing.meter.error_report_triggered",
      "livemode": false,
      "created": "2024-09-17T06:20:52.246Z",
      "related_object": {
        "id": "mtr_test_61R9IeP0SgKbYROOx41PEAQhH0qO23oW",
        "type": "billing.meter",
        "url": "/v1/billing/meters/mtr_test_61R9IeP0SgKbYROOx41PEAQhH0qO23oW"
      }
    }
  }
}
```

## Support event types where Stripe waits for a response

Stripe sends most event types asynchronously; however, for certain event types, Stripe waits for a response. The presence or absence of a response from the event destination directly influences Stripe’s actions regarding these specific event types.

Event Grid destinations provide limited support for event types that require a response:

- You can’t subscribe to the `issuing_authorization.request` event type for Event Grid destinations. Instead, set up a [webhook endpoint](https://docs.stripe.com/webhooks.md) to subscribe to this event type. Use `issuing_authorization.request` to authorize purchase requests in real-time. This requires your destination to approve or decline requests by responding to the event. Event Grid handles the response to Stripe before sending it to your consumers. As a result, this destination type can’t use this event type to authorize any payments.
- You can subscribe to `checkout_sessions.completed` when using Event Grid. However, this doesn’t [handle redirect behavior](https://docs.stripe.com/checkout/fulfillment.md#redirect-hosted-checkout) when you embed [Checkout](https://docs.stripe.com/payments/checkout.md) directly in your website or redirect customers to a Stripe-hosted payment page. Delivering a `checkout_sessions.completed` event to Event Grid won’t affect redirect behavior. To change Checkout redirect behavior, process this event type with a [webhook endpoint](https://docs.stripe.com/webhooks.md).

## See also

- [List of thin event types](https://docs.stripe.com/api/v2/core/events/event-types.md)
- [List of snapshot event types](https://docs.stripe.com/api/events/.md)
- [Event destinations overview](https://docs.stripe.com/event-destinations.md)
- [Send events to webhook endpoints](https://docs.stripe.com/webhooks.md)