# Send events to Amazon EventBridge Consume Stripe events in your AWS infrastructure. > #### Enable Workbench > > To send events to Amazon EventBridge, enable Workbench in your [Developer settings](https://dashboard.stripe.com/settings/developers) in the Dashboard. [Amazon EventBridge](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-what-is.html) is a serverless, event-driven service provided by AWS that helps connect your applications together by ingesting, transforming, and delivering events. Integrating with EventBridge using an event destination allows you to receive event data from Stripe directly in your AWS account, instead of handling the traffic and managing integration code logic yourself. When events are received, EventBridge can route them to [20 supported targets](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-targets.html) to process or trigger business automations. ## Send events to Amazon EventBridge Complete the steps below to receive events in EventBridge. This involves creating a new event destination in Workbench and setting up EventBridge configuration in the [AWS Management Console](https://docs.aws.amazon.com/awsconsolehelpdocs/latest/gsg/learn-whats-new.html). > You won’t receive any event data in your Amazon EventBridge until you complete each step. ## 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 Amazon EventBridge. Create an event destination using Workbench in the Dashboard or programmatically with the [API](https://docs.stripe.com/api/v2/event-destinations.md). #### Dashboard To create an event destination in the Dashboard: 1. Open the [Webhooks](https://dashboard.stripe.com/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 account](https://docs.stripe.com/get-started/account/orgs.md), select **Accounts** to listen to events from accounts in your organization. If you have [Connect platforms](https://docs.stripe.com/connect.md) as members of your organizations and want to listen to events from the all the platforms’ connected accounts, select **Connected accounts**. 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 **Amazon EventBridge** as your destination type, then click **Continue**. 1. Enter the following information: - [AWS account ID](https://docs.aws.amazon.com/accounts/latest/reference/manage-acct-identifiers.html): The AWS account that hosts your EventBridge instance for receiving events. - [AWS region](https://aws.amazon.com/about-aws/global-infrastructure/regions_az/): The AWS region that hosts your EventBridge instance for receiving events. - (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**. ![Register a new webhook using the Webhooks tab](https://b.stripecdn.com/docs-statics-srv/assets/create-webhook.f728025897e9e4ca2ba623abe34995a0.png) Register a new webhook in the **Webhooks** tab #### API Use the [API](https://docs.stripe.com/api/v2/event-destinations.md) to create a new event destination for Amazon EventBridge. 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/event-destinations/create.md#v2_create_event_destinations-events_from) parameter and set its enum value to `accounts`. ```curl curl -X POST https://api.stripe.com/v2/core/event_destinations \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: {{STRIPE_API_VERSION}}" \ --json '{ "name": "My Event Destination", "description": "This is my event destination, I like it a lot", "type": "amazon_eventbridge", "event_payload": "thin", "enabled_events": [ "v1.billing.meter.error_report_triggered" ], "amazon_eventbridge": { "aws_account_id": "012345678910", "aws_region": "us-east-1" } }' ``` ```cli stripe v2 core event_destinations create \ --name="My Event Destination" \ --description="This is my event destination, I like it a lot" \ --type=amazon_eventbridge \ --event-payload=thin \ --enabled-events="v1.billing.meter.error_report_triggered" \ --amazon-eventbridge.aws-account-id=012345678910 \ --amazon-eventbridge.aws-region=us-east-1 ``` ```ruby # Set your secret key. Remember to switch to your live secret key in production. # See your keys here: https://dashboard.stripe.com/apikeys client = Stripe::StripeClient.new("<>") event_destination = client.v2.core.event_destinations.create({ name: 'My Event Destination', description: 'This is my event destination, I like it a lot', type: 'amazon_eventbridge', event_payload: 'thin', enabled_events: ['v1.billing.meter.error_report_triggered'], amazon_eventbridge: { aws_account_id: '012345678910', aws_region: 'us-east-1', }, }) ``` ```python # Set your secret key. Remember to switch to your live secret key in production. # See your keys here: https://dashboard.stripe.com/apikeys client = StripeClient("<>") event_destination = client.v2.core.event_destinations.create({ "name": "My Event Destination", "description": "This is my event destination, I like it a lot", "type": "amazon_eventbridge", "event_payload": "thin", "enabled_events": ["v1.billing.meter.error_report_triggered"], "amazon_eventbridge": {"aws_account_id": "012345678910", "aws_region": "us-east-1"}, }) ``` ```php // Set your secret key. Remember to switch to your live secret key in production. // See your keys here: https://dashboard.stripe.com/apikeys $stripe = new \Stripe\StripeClient('<>'); $eventDestination = $stripe->v2->core->eventDestinations->create([ 'name' => 'My Event Destination', 'description' => 'This is my event destination, I like it a lot', 'type' => 'amazon_eventbridge', 'event_payload' => 'thin', 'enabled_events' => ['v1.billing.meter.error_report_triggered'], 'amazon_eventbridge' => [ 'aws_account_id' => '012345678910', 'aws_region' => 'us-east-1', ], ]); ``` ```java // Set your secret key. Remember to switch to your live secret key in production. // See your keys here: https://dashboard.stripe.com/apikeys StripeClient client = new StripeClient("<>"); EventDestinationCreateParams params = EventDestinationCreateParams.builder() .setName("My Event Destination") .setDescription("This is my event destination, I like it a lot") .setType(EventDestinationCreateParams.Type.AMAZON_EVENTBRIDGE) .setEventPayload(EventDestinationCreateParams.EventPayload.THIN) .addEnabledEvent("v1.billing.meter.error_report_triggered") .setAmazonEventbridge( EventDestinationCreateParams.AmazonEventbridge.builder() .setAwsAccountId("012345678910") .setAwsRegion("us-east-1") .build() ) .build(); EventDestination eventDestination = client.v2().core().eventDestinations().create(params); ``` ```node // Set your secret key. Remember to switch to your live secret key in production. // See your keys here: https://dashboard.stripe.com/apikeys const stripe = require('stripe')('<>'); const eventDestination = await stripe.v2.core.eventDestinations.create({ name: 'My Event Destination', description: 'This is my event destination, I like it a lot', type: 'amazon_eventbridge', event_payload: 'thin', enabled_events: ['v1.billing.meter.error_report_triggered'], amazon_eventbridge: { aws_account_id: '012345678910', aws_region: 'us-east-1', }, }); ``` ```go // Set your secret key. Remember to switch to your live secret key in production. // See your keys here: https://dashboard.stripe.com/apikeys sc := stripe.NewClient("<>") params := &stripe.V2CoreEventDestinationCreateParams{ Name: stripe.String("My Event Destination"), Description: stripe.String("This is my event destination, I like it a lot"), Type: stripe.String("amazon_eventbridge"), EventPayload: stripe.String("thin"), EnabledEvents: []*string{stripe.String("v1.billing.meter.error_report_triggered")}, AmazonEventbridge: &stripe.V2CoreEventDestinationCreateAmazonEventbridgeParams{ AwsAccountID: stripe.String("012345678910"), AwsRegion: stripe.String("us-east-1"), }, } result, err := sc.V2CoreEventDestinations.Create(context.TODO(), params) ``` ```dotnet // Set your secret key. Remember to switch to your live secret key in production. // See your keys here: https://dashboard.stripe.com/apikeys var options = new Stripe.V2.Core.EventDestinationCreateOptions { Name = "My Event Destination", Description = "This is my event destination, I like it a lot", Type = "amazon_eventbridge", EventPayload = "thin", EnabledEvents = new List { "v1.billing.meter.error_report_triggered" }, AmazonEventbridge = new Stripe.V2.Core.EventDestinationCreateAmazonEventbridgeOptions { AwsAccountId = "012345678910", AwsRegion = "us-east-1", }, }; var client = new StripeClient("<>"); var service = client.V2.Core.EventDestinations; Stripe.V2.Core.EventDestination eventDestination = service.Create(options); ``` ## Associate the partner event source [AWS Console] After you set up an event destination, Stripe creates a [partner event source](https://docs.aws.amazon.com/eventbridge/latest/APIReference/API_EventSource.html) in the AWS account and region you provided during configuration. To start receiving events, you need to associate this event source with an [event bus](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-event-bus.html) within 7 days of the event destination’s creation. If you don’t associate it within this time frame, Amazon automatically deletes the pending event source. After an event source is deleted, your Stripe event destination is automatically disabled and you must create a new destination to receive events. 1. Under **EventBridge** in your [AWS console](https://docs.aws.amazon.com/awsconsolehelpdocs/latest/gsg/learn-whats-new.html), go to the [Partner event sources page](https://console.aws.amazon.com/events/home#/partners) that’s listed in the **Integration** section of the left-hand panel. ![Navigate to **Partner event sources**](https://b.stripecdn.com/docs-statics-srv/assets/aws-select-partner-event-source.14ff917248eeb4f333195e6b3a431447.png) 1. Use the **Region** dropdown list located at the top of the console to select the region you chose when configuring your [event destination in Workbench](https://docs.stripe.com/event-destinations/eventbridge.md#add-eventbridge-destination). ![Select your AWS region](https://b.stripecdn.com/docs-statics-srv/assets/aws-region.6a68960287ba6356f8e856501295a039.png) 1. Choose the newly created partner event source in the dropdown. To find the Event Source ARN field in Workbench, select your event destination. Your partner source matches the part of the ARN that reads `event-source/aws.partner/stripe.com/{UNIQUE_ID}`. Then, click **Associate with event bus**. ![Associate the partner event source with event bus](https://b.stripecdn.com/docs-statics-srv/assets/aws-associate-partner-event-source.c89d540961356ff06e3fb095956ba80f.png) 1. Select permissions you want to grant for this event bus as needed, then click **Associate**. ![Select permissions and finalize association](https://b.stripecdn.com/docs-statics-srv/assets/aws-associate-event-bus.28dcbc4781d814799076258c8f1b9a04.png) ## Create EventBridge rules [AWS Console] EventBridge groups and routes events based on [rules](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-rules.html) you define. After you create an event destination and associate its partner event source to an event bus, you must define rules to make sure that EventBridge knows how to handle the events it receives on the event bus. You can repeat these steps multiple times to define multiple rules. 1. Navigate to the AWS management console, then click [Rules](https://console.aws.amazon.com/events/home#/events). ![Navigate to **Rules**](https://b.stripecdn.com/docs-statics-srv/assets/aws-select-rules.f385d0e668caafc9614584e2ae635138.png) 1. Click **Create Rule**, then provide a rule name and description. ![Provide rule name and description](https://b.stripecdn.com/docs-statics-srv/assets/aws-define-rule.ce885bcbea4d7492f082eba2f38fd840.png) 1. Select your event bus from the dropdown. To find your event bus, go to Workbench, select your destination in the **Webhooks** tab, then view the **Event source ARN** field, which shares the same name as your event source ARN. Then, click **Next**. 1. Under **Event source**, select **AWS events or EventBridge partner events** because Stripe events are partner events. ![Select event source](https://b.stripecdn.com/docs-statics-srv/assets/aws-event-source.29ee4d4e795b0f7d89db7163ab7b9ac5.png) 1. (Optional) Include a sample Stripe event. 1. Under **Creation Method**, choose **Use pattern form** to use a predefined pattern. Alternatively, you can create a custom event pattern. ![Use a predefined rule patter](https://b.stripecdn.com/docs-statics-srv/assets/aws-create-rule-pattern.3246a6c5a409b1b0571f56acc6e7b91b.png) 1. Under **Event Pattern**, select **EventBridge partners** as the **Event Source**. 1. Under **Event Pattern**, select **Stripe** as the **Partner**. 1. Select the appropriate event type you want to create a rule for or select **All events** to match this rule to all event types, then click **Next**. 1. Select the [target](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-targets.html) you want this rule to send events to, then click **Next**. > #### Recommendation > > We recommend you [create a CloudWatch Logs target](https://repost.aws/knowledge-center/cloudwatch-log-group-eventbridge) for each event bus to enable monitoring for your event destination. Consider using other [common architecture patterns](https://docs.stripe.com/event-destinations/eventbridge.md#common-architecture) with EventBridge and Stripe events. ![Select rule target](https://b.stripecdn.com/docs-statics-srv/assets/aws-select-target.d9da569a26cf0d6fcc81f753b16d0e60.png) 1. Add optional tags, then click **Next**. 1. Review your rule and make changes as needed, then click **Create Rule**. Your Stripe events are now successfully delivered to EventBridge and its corresponding targets defined in your rule. ## 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/stripe-shell/overview.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 `outbound_payment.posted` event: ```bash stripe preview trigger outbound_payment.posted Setting up fixture for: finaddr_info Running fixture for: finaddr_info Setting up fixture for: create_recipient Running fixture for: create_recipient Setting up fixture for: create_destination Running fixture for: create_destination Setting up fixture for: create_outbound_payment Running fixture for: create_outbound_payment ``` ## Event delivery behaviors This section helps you understand different behaviors to expect regarding how Stripe sends events to Amazon EventBridge. ### 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 Amazon EventBridge. ### 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 Amazon EventBridge destinations have several statuses that describe their readiness to receive events: - **Active**: Stripe is sending events to Amazon EventBridge if you have associated the partner event source in AWS. - **Disabled**: Stripe isn’t sending events to Amazon EventBridge. Your destination will be in this status either because you manually disabled it or Stripe automatically disabled it due to an AWS misconfiguration. ## Event structure EventBridge uses its own [event structure](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-events-structure.html) that wraps the Stripe `event` JSON object within a top-level `detail` field. This example is a `customer.created` event payload from EventBridge: ```json { "version":"0", "id":"17e8dff5-d6cd-3770-ace9-aeac02b6ac3f", "detail-type":"customer.created", "source":"aws.partner/stripe.com/ed_61PgtRTG5aTCIz98516PLsRGLISQK0Otk6FWKjBrcDia", "account":"506417113029", "time":"2024-03-07T18:27:56Z", "region":"us-west-2", "resources":[ "arn:aws:events:us-west-2::event-source/aws.partner/stripe.com/ed_61PgtRTG5aTCIz98516PLsRGLISQK0Otk6FWKjBrcDia" ], "detail":{ "id":"evt_1OrlfcFvFEcV7KhhYdemHC4q", "object":"event", "api_version":"2023-10-16", "created":1709836076, "data":{ "object":{ "id":"cus_Ph9zopzZYifGvU", "object":"customer", "address":null, "balance":0, "created":1709836076, "currency":null, "default_source":null, "delinquent":false, "description":null, "discount":null, "email":null, "invoice_prefix":"2331D388", "invoice_settings":{ "custom_fields":null, "default_payment_method":null, "footer":null, "rendering_options":null }, "livemode":true, "metadata":{ }, "name":"coolest customer", "next_invoice_sequence":1, "phone":null, "preferred_locales":[ ], "shipping":null, "tax_exempt":"none", "test_clock":null } }, "livemode":true, "pending_webhooks":0, "request":{ "id":"req_id3MuDYoBgmN4d", "idempotency_key":"6fbb7f75-0658-4989-989e-706fab3abe76" }, "type":"customer.created" } } ``` ## Support events 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. Amazon EventBridge destinations offer limited support for event types that require a response: - You can’t subscribe to the `issuing_authorization.request` event type for Amazon EventBridge 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. EventBridge 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 Amazon EventBridge. 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 Amazon EventBridge won’t affect redirect behavior. To influence Checkout redirect behavior, process this event type with a [webhook endpoint](https://docs.stripe.com/webhooks.md). ## Common architecture patterns with EventBridge and Stripe events Consider the following architectural patterns when you use Amazon EventBridge with Stripe: - **Trigger serverless functions with [Lambda](https://aws.amazon.com/lambda/) to define business automations**: Send Stripe events from EventBridge to Lambda to trigger serverless compute functions, such as creating a shipping label after a payment succeeds. - **Enable event monitoring with [CloudWatch](https://aws.amazon.com/cloudwatch/)**: Send events from EventBridge to CloudWatch Logs to store events as log data that you can interactively search and analyze. Monitor usage patterns and errors with CloudWatch. Consider setting up alerts for errors (for example, when an EventBridge rule is broken). - **Trigger low and no code workflows with [Step Functions](https://aws.amazon.com/step-functions/)**: Send events to a StepFunction workflow that trigger your business scenarios, such as notifying your customers that their trial is about to end. - **Fan out events to internal systems with [Simple Notification Service (SNS)](https://aws.amazon.com/sns/) or [Simple Queue Service (SQS)](https://aws.amazon.com/sqs/)**: Send Stripe events to SNS or SQS to fan out Stripe event data to your internal teams to make sure that they can own and process them. ## 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)