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 merchant 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, including how to configure a webhook for your app and manage webhooks for different API versions.
Continuous polling vs. webhook subscriptionsAnchor 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/createtopic 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
Shopify sends the webhook with an order payload to the registered 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 conceptsAnchor link to section titled "Webhook concepts"
To help orient you with the content in this guide, the following definitions explain webhook concepts:
Webhook: A single event message. Shopify sends a webhook to an app's webhook subscription endpoint. A webhook contains a JSON or XML payload in the body, and metadata in the headers.
Webhook topic: A class of webhook events. A topic controls when webhook events are created and what's in the webhook payload. For example,
orders/create webhook events are sent whenever an order is created for a shop, and contain the new order as the payload.
The topic (class of events) that the app wants to receive.
A webhook subscription endpoint, or the destination where Shopify sends webhooks (event messages) for the specified topic.
Webhook headersAnchor 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:
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|
||Identify unique webhooks|
||Identify the associated store|
Webhook behaviorAnchor link to section titled "Webhook behavior"
The following sections describe how webhooks act in Shopify.
Webhook orderAnchor 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 versionsAnchor link to section titled "API versions"
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.
LimitationsAnchor link to section titled "Limitations"
Ordering isn't guaranteed between different topics for the same resource. For example, it's possible that a
products/updatewebhook might be delivered before a
The webhooks API provides "at least once" delivery of webhook events. This means that an endpoint might receive the same webhook event more than once. You can detect duplicate webhook events by comparing the
X-Shopify-Webhook-Idheader to previous events.
Webhook delivery isn't always guaranteed. You should therefore implement reconciliation jobs to fetch data from Shopify periodically.
Testing webhooksAnchor link to section titled "Testing webhooks"
You can test your webhook configuration, or view the webhook payload, by triggering the webhook. You can trigger webhooks in the following ways:
- Manually, using the Shopify CLI
webhook triggercommand. Manually triggering webhooks doesn't test your webhook subscriptions.
- By performing the related action in a Shopify store that has your app installed.
TroubleshootingAnchor link to section titled "Troubleshooting"
If a webhook has 13 or more consecutive failed deliveries, then Shopify notifies you by email. A webhook is removed when 19 consecutive retried delivery attempts fail.
If your app was created in the Partner Dashboard or using Shopify CLI, then you can use the webhook delivery metrics report to troubleshoot delivery failures and get information on performance.