Webhooks overview
Webhooks allow apps to stay in sync with Shopify data or perform an action after a specific event occurs in a shop. Webhooks are a performant alternative to continuously polling for changes to a shop's data.
For example, a webhook can notify your app when a user changes a product in the Shopify admin. Your app can then perform an action when the product change occurs.
This guide introduces how webhooks work, introducing terminology and behavior.
Continuous polling vs. webhook subscriptions
Anchor link to section titled "Continuous polling vs. webhook subscriptions"Webhooks are a performant alternative to continuous polling. The following example uses the orders/create
webhook topic to illustrate the difference:
The app subscribes to the
orders/create
topic for a shop and listens for order creation events.The app specifies an HTTPS endpoint hosted by the app server to receive events for the topic.
An order on the shop is created.
The event is published to the
orders/create
topic.Shopify sends the webhook with an order payload to the subscription endpoint.
Common webhook use cases include the following:
Sending notifications to IM clients and pagers
Collecting data for data-warehousing
Integrating with accounting software
Filtering order items and informing shipping companies about orders
Removing customer data from a database for app uninstalls
Webhook concepts
Anchor link to section titled "Webhook concepts"Shopify can notify your app whenever an event of business significance occurred, for example when a new product is created for a shop. A webhook is an event message that's delivered to your app using HTTPS, Google Cloud Pub/Sub, or Amazon EventBridge.
Webhook topic
Anchor link to section titled "Webhook topic"Webhooks are organized into topics. Your app subscribes to one topic per shop to receive webhooks each time that type of event is triggered for that shop in Shopify. The topic defines the kind of event messages that the app receives. For example, your app can subscribe to the products/create
topic to be notified about new products that are created.
Topics have a name that 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 includes the topic and the subscription endpoint, which is the destination where Shopify sends webhooks
For example, if your app needs to know about new products that are created in a shop, then you can subscribe to the products/create
topic. Whenever a products/create event occurs, an event message is delivered to the endpoint the app set up as the destination when it subscribed.
Webhook headers
Anchor link to section titled "Webhook headers"In addition to the message payload, each webhook message has a variety of headers containing additional context.
For example, an orders/create
webhook can include the following headers:
The following header fields are used:
Field | Use |
---|---|
If you're using a PHP, or a Rack-based framework such as Ruby on Rails or Sinatra, then the header is |
Verify webhooks that are sent using an HTTPS endpoint |
X-Shopify-Webhook-Id |
Identify unique webhooks |
X-Shopify-Shop-Domain |
Identify the associated store |
Time in UTC format. |
Identify the date and time when Shopify triggered the webhook |
Webhook behavior
Anchor link to section titled "Webhook behavior"The following sections describe how webhooks act in Shopify.
Webhook order
Anchor link to section titled "Webhook order"Webhooks are sent in order for each resource and topic combination. For example, each products/update
webhook for the same product is delivered in order.
API versions
Anchor link to section titled "API 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.
Limitations
Anchor link to section titled "Limitations"Ordering isn't guaranteed between different topics for the same resource. For example, it's possible that a
products/update
webhook might be delivered before aproducts/create
webhook.An endpoint might receive the same webhook event more than once. You can detect duplicate webhook events by comparing the
X-Shopify-Webhook-Id header
to previous events.Your app must be ready to accept the webhook. If it isn't set up to receive the webhook, then webhook delivery isn't guaranteed. Learn more about our retries mechanism. If a webhook is critical to your app, then you should implement reconciliation jobs to fetch data from Shopify periodically.
Testing webhooks
Anchor link to section titled "Testing webhooks"You can test your webhook subscriptions, or view the webhook payload, by triggering the webhook. You can trigger webhooks in the following ways:
- Manually, using the Shopify CLI
webhook trigger
command. Manually triggering webhooks doesn't test your webhook subscriptions. - By performing the related action in a Shopify store that has your app installed.
- Learn about webhook best practices, including how to respond quickly to webhooks, track failures, recover webhooks, and more.
- Learn how to configure your app to use webhooks.