Amazon EventBridge webhook delivery

You can integrate your app with Amazon EventBridge to manage large volumes of event notifications and receive Shopify webhooks using an event bus.

EventBridge lets you process events at the rate that works for your tech stack without getting overwhelmed. It’s highly scalable and resilient, and lets you accept more webhook traffic while reducing your infrastructure cost and complexity.

Requirements

  • You've created a public or custom app. Private apps can't integrate with EventBridge.
  • You've set up your Lambda function, SQS queue, or other EventBridge destination.
  • You have your 12-digit Amazon Web Services (AWS) Account ID from the AWS console.

How EventBridge integration works

EventBridge is a serverless, event-driven alternative to receiving webhooks via standard HTTP. Integrating with EventBridge lets you send event data to AWS directly, instead of needing to handle all that traffic yourself.

Diagram showing the workflow for building an EventBridge integration

To integrate your app with EventBridge, you first need to set up an event source in your Partner Dashboard. This tells Shopify to send events to AWS.

You then associate your event source with an event bus in the AWS console, and create rules for the event bus so that AWS knows what to do with the events received. You can route events to SQS, Lambda, or another similar service.

Finally, you subscribe to webhooks using the GraphQL Admin or REST Admin API, and supply your partner event source Amazon Resource Number (ARN), obtained in the AWS console, in your requests.

Step 1: Set up an event source

To begin integrating your app with EventBridge, set up an event source to tell Shopify to send events to AWS.

  1. In your Partner Dashboard, go to Apps and click the name of your app.
  2. Click App setup.
  3. In the Event Subscriptions section, under Amazon EventBridge, click Create source.
  4. Paste your AWS account ID, and choose your AWS region.
  5. Enter an event source name. All your event sources must have unique names, so if you have multiple apps, then consider a name that matches your app.
  6. Click Create.

Step 2: Configure an event bus

After you set up an event source to deliver Shopify events to AWS, configure an event bus to handle those events.

  1. In the AWS console, under EventBridge, navigate to Partner event sources page.
  2. In the Region drop-down menu, select the AWS region that you chose when you set up your event source. These regions must match for the event bus to connect with the event source.
  3. Click the event source you created in step 1. Make note of the ARN found under Partner event source ARN. This will be the address you use later to create webhook subscriptions.
  4. Click Associate with event bus.
  5. On the next page, click Associate.

Step 3: Create a rule

After you've set up your event source and associated it with an event bus, you need to create a rule that tells AWS what to do with events it receives on the event bus. EventBridge groups and sorts the events that your event source sends based on the rules that you define.

  1. In the AWS console navigation menu, click Rules.
  2. In the drop-down menu, select your event bus.
  3. Click Create rule.
  4. Enter a rule name.
  5. Optional: Enter a description for the rule.
  6. In the Define pattern section, choose Event pattern, and select Pre-defined pattern by service. Alternatively, you can define a custom event pattern for your rule.
  7. In the list of providers, choose All Events.
  8. In the Service name drop-down menu, select Shopify. This makes sure that only events sent by Shopify are processed by this rule.
  9. In the Select event bus section, select the event bus that will use this rule.
  10. In the Select targets section, choose a Lambda function or SQS queue. Events processed by this rule will be sent to the function or queue that you select.
  11. Click Create.
  12. Optional: Repeat steps 3-11 to define multiple rules.

Define a custom event pattern

You can choose to process events separately, depending on factors such as which shop generated the event or which resource triggered the event.

  1. When creating a rule, select Event pattern in the Define pattern section and then select Custom pattern.
  2. Enter a custom pattern that matches the structure of an EventBridge payload and click Save.

Custom event pattern examples

Event patterns in EventBridge rules have the same structure as the payloads that they match. The matching values are added to an array and compared using OR logic. You can also match by prefix using the prefix key.

To match a specific shop domain, use the following pattern. Make sure to change the example domain to your store's domain:

To match all products events, use the following pattern:

Step 4: Create webhook subscriptions

After you configure your event bus and rules in AWS, you can create webhook subscriptions using the Partner event source ARN you obtained from step 2.

Data sent using webhooks is divided by topic. Consult the GraphQL Admin API or REST Admin API reference for the complete list of supported webhook topics. Subscriptions can be created when your app is installed on a shop and the OAuth flow completes.

Subscribe to a webhook with GraphQL

Use the eventBridgeWebhookSubscriptionCreate mutation to subscribe to a webhook. The following example shows how to subscribe to the PRODUCTS_CREATE webhook.

POST /admin/api/2021-04/graphql.json

Query HTTP and EventBridge subscriptions using GraphQL

Query WebhookSubscription to retrieve a list of HTTP and Eventbridge subscriptions. The following example shows how to retrieve the first 10 subscriptions.

POST /admin/api/2021-04/graphql.json

Subscribe to a webhook with REST

Use the Webhook resource to create a webhook subscription with REST. Subscribing with REST is similar to subscribing to HTTP webhooks, but an ARN is specified as the address.

POST /admin/api/2021-04/webhooks.json

EventBridge payloads

The following is an example payload from EventBridge. You can use the information in EventBridge payloads to define a custom event pattern in EventBridge.

Large payloads

Occasionally, a shop might have very large resources. If a Shopify resource would result in a payload larger than 255 KB, then a special payload will be sent with the following error message. You can use the resource ID in the X-Shopify-Product-Id field to request the resource using the REST Admin or GraphQL Admin API.

Next steps