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, including how to configure a webhook for your app and manage webhooks for different API versions.
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 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 concepts
Anchor 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.
Webhook subscription: A persisted data object that an app creates using the REST Admin API or GraphQL Admin API, which defines the following:
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 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.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-Id
header to previous events.Webhook delivery isn't always guaranteed. You should therefore implement reconciliation jobs to fetch data from Shopify periodically.
Testing webhooks
Anchor 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 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.
Troubleshooting
Anchor 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.
Developer resources
Anchor link to section titled "Developer resources"- 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.