About webhooks
When your app needs information about specific events that have occurred on a shop, it can subscribe to Shopify webhook topics as a mechanism for receiving near-real-time data about these events.
Shopify webhooks are useful for keeping your app in sync with Shopify data, or as a trigger perform an additional action after that event has occurred. They are also a performant alternative to continuously polling for changes to a shop's data.
This guide provides a quick primer on when to use APIs versus webhooks, as well as key terminology and behaviors that are specific to Shopify webhooks.
Examples of when your app might use webhooks
Anchor link to section titled "Examples of when your app might use webhooks"- Sending notifications about changes in inventory levels to inventory management clients and pagers
- Informing shipping companies about changes in orders, returns, or refunds
- Removing customer data from a database for app uninstalls
- Integrating data about orders with accounting software
- Updating a product's warranty price based on changes to the product's price
APIs for continuous polling vs. Webhooks for events data
Anchor link to section titled "APIs for continuous polling vs. Webhooks for events data"The following example uses the orders/create webhook topic to illustrate the difference between polling an API for data about events, versus subscribing to a webhook topic to receive data about events.
The app subscribes to the
orders/createtopic for a shop and listens for order creation events.The app specifies an endpoint to receive webhooks for the
orders/createtopic. For example, this may be an HTTPS endpoint hosted by the app server. This endpoint is where the app listens for webhooks.Suppose now that an order is created from that shop.
This triggers a webhook to be published to the
orders/createtopic.Shopify sends that webhook, which includes headers and an order payload, to the specified subscription endpoint.
Key terminology
Anchor link to section titled "Key terminology"Webhook topic
Anchor link to section titled "Webhook topic"Webhooks are organized into topics. Your app subscribes to one or more topics to receive webhooks. Once installed on a shop, your app will receive webhooks each time that type of event is triggered for that shop.
The webhook topic defines the kind of event messages that your app receives. For example, your app can subscribe to the products/create topic to be notified about new products that are created. The topic name identifies the nature of the event that's triggered.
Webhook subscription
Anchor link to section titled "Webhook subscription"A webhook subscription declares the app’s intention to receive webhooks for a topic. A subscription is defined by:
- The topic name
- The subscription endpoint
The endpoint is the destination that Shopify sends the webhooks to. This can be either a cloud-based event bus, or HTTPS. Today, Shopify provides support for, and is integrated with, Google Pub/Sub and Amazon EventBridge. Shopify recommends using Google Pub/Sub whenever possible.
Each webhook is made up of headers and a payload. Headers contain metadata about the webhook, like the shop that the app was installed on and where the event occurred.
Every Shopify webhook will include at least the following headers. Some topics may have additional headers containing more context.
| Header | What it is |
|---|---|
X-Shopify-Topic |
The name of the topic. Use the webhooks references to match this to the enum value when configuring webhook subscriptions using the Admin API. |
X-Shopify-Hmac-Sha256 |
Verification, when using HTTPS delivery. |
X-Shopify-Shop-Domain |
Identifying the associated store. Especially useful when configuring webhook subscriptions using the Admin API. |
X-Shopify-Webhook-Id |
Identifying unique webhooks. |
X-Shopify-Triggered-At |
Identifying the date and time when Shopify triggered the webhook. |
X-Shopify-Event-Id |
Identifying the event that occurred. |
What to expect when working with Shopify event data
Anchor link to section titled "What to expect when working with Shopify event data"Below are some key things to remember when working with Shopify event data and webhooks.
Ordering event data
Anchor link to section titled "Ordering event data"As with other webhook systems, Shopify doesn't guarantee ordering within a topic, or across different topics for the same resource either. For example, it's possible that a products/update webhook might be delivered before a products/create webhook.
Shopify recommends using timestamps provided in the header (X-Shopify-Triggered-At) or in the payload itself (updated_at) to organize webhooks.
Working with versions
Anchor link to section titled "Working with versions"The header X-Shopify-API-Version specifies what version of the Admin API was used to serialize the webhook event payload. You can configure your app to use a specific API version for all webhooks and that version will be used whenever possible.
If an app is set to use an API version that is no longer supported, then Shopify will fall forward to use the oldest supported version.
Handling duplicate webhooks
Anchor link to section titled "Handling duplicate webhooks"In rare instances, your app may receive the same webhook event more than once. Shopify recommends detecting duplicate webhook events by comparing the X-Shopify-Event-Id to previous events'.
- Get your app set up quickly with its first webhook subscription
- Learn about the nuances of webhook subscriptions, including alternative ways to configure your subscription
- Once your app is set up with subscriptions, learn how to customize webhooks to meet your bespoke needs