Amazon EventBridge webhook delivery
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.
How EventBridge integration works
Anchor link to section titled "How EventBridge integration works"EventBridge is a serverless, event-driven alternative to receiving webhooks through standard HTTP. Integrating with EventBridge lets you send event data to AWS directly, instead of handling that traffic yourself.
The following diagram shows the workflow to integrate your app with EventBridge:
In your Partner Dashboard, set up an event source. This tells Shopify to send events to AWS.
In the AWS console, associate your event source with an event bus.
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.
Subscribe to webhooks using the GraphQL Admin API or REST Admin API. Use your partner event source Amazon Resource Number (ARN) supplied in your requests. You obtain the ARN from the AWS console.
Requirements
Anchor link to section titled "Requirements"You're familiar with how webhooks work.
You're familiar with the webhooks best practices.
You're authenticated with the GraphQL Admin API or REST Admin API.
You've created an app.
You've set up your AWS Lambda function, SQS queue, or other EventBridge destination.
You have your 12-digit Amazon Web Services (AWS) Account ID from the AWS console.
Step 1: Set up an event source
Anchor link to section titled "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.
Navigate to your app's settings page in the Partner Dashboard or Shopify admin:
- In your Partner Dashboard, go to Apps.
- Click the name of your app.
- Click App setup.
- In your Shopify admin, go to Settings.
- Click Apps and sales channels.
- Click Develop apps for your store.
- Click the name of your app.
- Click Configuration.
- Next to Admin API integration, click Configure.
Under Amazon EventBridge, click Create source.
Paste your AWS account ID, and choose your AWS region.
You need the AWS region when you associate an event bus with the source.
Provide a unique event source name.
Each event source requires a unique name. If you have multiple apps, then consider a name that matches your app.
Click Create.
Step 2: Associate an event bus
Anchor link to section titled "Step 2: Associate an event bus"After you set up an event source to deliver Shopify events to AWS, associate the source with a bus to handle events.
In the AWS console, under EventBridge, navigate to the Partner event sources page.
In the Region drop-down list, 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.
Click the event source that you created, and note the ARN found under Partner event source ARN.
You need this address to subscribe to a webhook.
Click Associate with event bus.
On the next page, click Associate.
Step 3: Create a rule
Anchor link to section titled "Step 3: Create a rule"EventBridge groups and sorts the events that your event source sends based on the rules that you define. After you set up your event source and associate it with an event bus, create a rule that tells AWS what to do with events it receives on the bus.
To define multiple rules, repeat this step for each rule.
In the AWS console navigation menu, click Rules.
In the drop-down list, select your event bus.
Click Create rule.
Provide a rule name.
Provide a description for the rule.
In the Define pattern section, choose Event pattern, and select Pre-defined pattern by service.
You can also define a custom event pattern for your rule.
In the list of providers, choose All Events.
In the Service name drop-down list, select Shopify.
This makes sure that only events that Shopify sends are processed by this rule.
In the Select event bus section, select the event bus that will use this rule.
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.
Click Create.
Define a custom event pattern
Anchor link to section titled "Define a custom event pattern"When you create a rule, you can process events separately depending on factors like which shop generated the event or which resource triggered the event.
Event patterns in EventBridge rules have the same structure as the payloads that they match. Matching values are added to an array and compared using OR
. You can also match by prefix using the prefix key.
In the Define pattern section, select Event pattern.
Select Custom pattern.
Provide a custom pattern that matches the structure of an EventBridge payload.
Click Save.
Custom event example patterns
Anchor link to section titled "Custom event example patterns"Use the following pattern to match on a specific shop domain:
Use the following pattern to match all products
events:
Step 4: Subscribe to a webhook
Anchor link to section titled "Step 4: Subscribe to a webhook"Subscribe to webhooks when your app is installed on a shop and the OAuth flow completes.
Webhook data is divided by topic. Refer to the GraphQL Admin API or REST Admin API reference for the complete list of supported webhook topics.
The following examples show you how to subscribe to a webhook using GraphQL and REST.
Use the eventBridgeWebhookSubscriptionCreate
mutation to subscribe to a webhook with GraphQL.
- Set
arn
to the ARN that you retrieved.
Request: POST /admin/api/2023-07/graphql.json
Example (GraphQL): Retrieve HTTP and EventBridge subscriptions
Anchor link to section titled "Example (GraphQL): Retrieve HTTP and EventBridge subscriptions"Use the WebhookSubscription
object to retrieve a list of HTTP and EventBridge subscriptions.
The following example shows how to retrieve the first ten subscriptions:
Request: POST /admin/api/2023-07/graphql.json
Use the Webhook
resource to subscribe to a webhook with REST. Subscribing with REST is similar to subscribing to HTTP webhooks, with the following difference:
- Set
address
to the ARN that you retrieved.
POST /admin/api/2023-07/webhooks.json
EventBridge payload structure
Anchor link to section titled "EventBridge payload structure"You can use the information in EventBridge payloads to define a custom event pattern in EventBridge.
The following is an example payload from EventBridge:
Large payloads
Anchor link to section titled "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 is 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.
Test your configuration by manually triggering a webhook delivery using the Shopify CLI
webhook trigger
command. Manually triggering webhooks doesn't test your webhook subscriptions.Learn how to manage webhooks for different API versions.
Learn about the available topics for REST Admin API webhooks.
Learn about the available topics for GraphQL Admin API webhooks.