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 to 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.

Diagram showing how webhooks work compared to continuous polling

The app subscribes to the orders/create topic for a shop and listens for order creation events.
The app specifies an endpoint to receive webhooks for the orders/create topic. 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/create topic.
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 occurred.

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.

Headers

Anchor link to section titled "Headers"

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. 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 which version of the Admin API was used to serialize the webhook event payload.

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.

You can learn more about configuring your app to use a specific API version for all webhook subscriptions.

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 header to previous events' X-Shopify-Event-Id header.

Next steps

Anchor link to section titled "Next steps"

Get your app set up quickly with its first webhook subscription.
Consult the webhooks reference to explore a full list of topics and sample payloads.
After your app is set up with subscriptions, learn how to customize webhooks to meet your bespoke needs.