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
* 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
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.
1. The app subscribes to the `orders/create` topic for a shop and listens for order creation events.
1. 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.
1. Suppose now that an order is created from that shop.
1. This triggers a webhook to be published to the `orders/create` topic.
1. Shopify sends that webhook, which includes headers and an order payload, to the specified subscription endpoint.
## Key terminology
### 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.
> Info:
> Webhooks are divided by topic. Refer to the [Webhooks references](/docs/api/webhooks) for the complete list of supported webhook topics.
### 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
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. |
> Caution:
> When you're using Google Cloud Pub/Sub or Amazon EventBridge for delivery of your webhooks, you receive a JSON payload for topics, but there will be additional fields included beyond the sample payloads displayed in the [Webhooks reference](/docs/api/webhooks).
## 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
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
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](/docs/apps/build/webhooks/subscribe/use-newer-api-version).
### 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
* Get your app set up quickly with [its first webhook subscription](/docs/apps/build/webhooks/subscribe/get-started).
* Consult the [webhooks reference](/docs/api/webhooks) to explore a full list of topics and sample payloads.
* After your app is set up with subscriptions, learn how to [customize webhooks](/docs/apps/build/webhooks/customize) to meet your bespoke needs.
