Webhooks overview

Webhooks are a performant alternative to continuous polling. The following example uses the orders/create webhook topic to illustrate the difference:

1. The app subscribes to the orders/create topic for a shop and listens for order creation events.

2. The app specifies an HTTPS endpoint hosted by the app server to receive events for the topic.

3. An order on the shop is created.

4. The event is published to the orders/create topic.

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

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.

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:

The following sections describe how webhooks act in Shopify.

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.

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.

• 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 a products/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.

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.

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.

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