Send events to Azure Event Grid

Consume Stripe events in your Azure infrastructure.

Azure Event Grid 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 —including webhooks, Azure functions, or Event Hub —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 in your Azure subscription (defined as an event destination on Stripe). Then, Azure event subscriptions route these events to your configured 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 in your subscription. 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:

Use the search bar to select Subscriptions .
Select the subscription you want to use for Event Grid from the subscription list.
On the Subscription page, click Settings > Resource providers .
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.
Select Microsoft.EventGrid in the provider list.
Select Register on the command bar.
Refresh to make sure the status of Microsoft.EventGrid is changed to Registered .

Create a partner authorization Azure portal

Create a partner authorization in the Azure portal so Stripe has consent to create a partner topic in the subscription and resource group you designate.

Sign in to the Azure portal.
In the search bar at the top, enter Partner Configurations , and select Event Grid Partner Configurations under Services in the results.
On the Event Grid Partner Configurations page, select + Create on the command bar.
On the Create Partner Configuration page, do the following steps:
In the Project Details section, select the subscription and the resource group where you want to allow the partner to create a partner topic.
In the Partner Authorizations section, specify a default expiration time for partner authorizations defined in this configuration.
To provide your authorization for a partner to create partner topics in the specified resource group, select the + Partner Authorization link.
Select Review + create .
On the Add partner authorization to create resources page, follow these steps to authorize Stripe:
Select Stripe from the list of verified partners
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.
Select Add .
Go to the Create Partner Configuration page, then verify that the partner is added to the partner authorization list at the bottom.
Select Review + create at the bottom of the page.
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 to send events to Event Grid.

Create an event destination using Workbench in the Dashboard or programmatically with the API.

To create an event destination in the Dashboard:

Open the Webhooks tab in Workbench.
Click Create new destination .
Select where you want to receive events from. Stripe supports two types of configurations: Your account and Connected accounts . Select Account to listen to events from your own account. If you created a Connect application 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, 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.

Select the event types that you want this destination to receive. Then, click Continue .
Select Azure Event Grid as your destination type, then click Continue .
Enter the following information:

Azure subscription ID : The subscription where your Stripe partner topic is created to receive events.
Azure resource group : The resource group that will contain the Stripe partner topic.
Azure region : 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.

Click Create destination .

Activate the partner topic Azure portal

After you set up an event destination, Stripe creates a partner topic 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.

In Workbench, click Complete setup in Azure for your event destination to activate your partner topic.

Alternatively, manually navigate to your partner topic in the Azure portal

Create event subscriptions and event handlers Azure Portal

After activating your Stripe partner topic, you must create at least one event subscription with an event handler 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:

In your Azure subscription, set up a service that’s supported as an event handler in Event Grid . This handler processes the events that Stripe sends to your partner topic. For example, you can use the Event Grid Viewer sample, which deploys a prebuilt web app that displays the Stripe event messages received from the partner topic.
In the Azure portal, type Event Grid Partner Topics in the search box, and select Event Grid Partner Topics .
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.
On the Event Grid Partner Topic page for the partner topic, select + Event Subscription on the command bar.
On the Create Event Subscription page, do the following steps:
Enter a name for the event subscription.
For Filter to Event Types , select types of events that your subscription receives.
For Endpoint Type , select the Azure service you used as your event handler.
Select the Configure an endpoint link .
On the Select Event Hub page, select configurations for the endpoint, and then select Confirm Selection .
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.

You can use the following command in either Stripe Shell or Stripe CLI. This example triggers a payment_intent.succeeded event:

Command Line

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

Thin event hydration

Thin events are notifications that include reference information about the API resource related to the event. When you send them to Azure Event Grid, you can use that information to fetch the full event or API resource object (also known as “event hydration”). In the Azure portal, you can set up this process by configuring event subscriptions using the supported event handlers of your choice. When you send thin events to webhook endpoints, you must fetch the complete event or resource data yourself using the API. This process provides you with fresh data by fetching the current state of the resource associated with every event.

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. Snapshot events record created in seconds, so distinct events can share a timestamp. Don’t use created to determine event order or whether you’ve already processed an event. Track event IDs to identify duplicate deliveries instead. 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 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, the Event object generated and sent to your destination is still based on the 2015-02-16 API version. You can’t change Event 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 objects. Retrieving an older Event 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 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:

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 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 when you embed Checkout 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 .