Webhooks overview

Webhooks are a useful tool for apps that want to stay in sync with Shopify or execute code after a specific event occurs in a shop. For example, you might want to trigger an action when a merchant creates a new product in the Shopify admin or when a customer places an order.

This guide introduces how webhooks work, including how to configure a webhook for your app and manage webhooks for different API versions.

What's a webhook?

A webhook is a single message sent by Shopify to an app's webhook subscription endpoint. A webhook contains a JSON or XML payload in the body, and metadata in the headers.

A webhook subscription is a persisted data object created by an app using the REST Admin API or GraphQL Admin API. It describes the topic that the app wants to receive, and a destination where Shopify should send webhooks of the specified topic. When an event for a given topic occurs, the webhook subscription sends a relevant payload to the destination.

A topic is a class of webhook events. It controls when webhook events are created and what's in the payload of the webhook.

How webhooks work

Your app subscribes to a topic and the webhook subscription sends a webhook to an endpoint.

For example, an app creates a webhook subscription on a shop for the orders/create topic and an HTTPS endpoint hosted by the app server. Whenever an order on the shop is created, the webhook subscription sends a webhook with an order payload to the registered endpoint.

Data about orders can change often. Instead of continuously polling for changes to orders, you can receive a webhook when a specific event occurs.

Diagram showing how webhooks work

Use cases

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

Anatomy of a webhook

After you subscribe to a webhook topic, Shopify sends a webhook notification each time an event for that topic occurs. This notification contains a JSON payload, and HTTP headers that provide context.

For example, an orders/create webhook includes the following headers:

  • X-Shopify-Topic: orders/create
  • X-Shopify-Hmac-Sha256: XWmrwMey6OsLMeiZKwP4FppHH3cmAiiJJAweH5Jo4bM=
  • X-Shopify-Shop-Domain: johns-apparel.myshopify.com
  • X-Shopify-API-Version: 2021-07
  • X-Shopify-Webhook-Id: b54557e4-bdd9-4b37-8a5f-bf7d70bcd043

Some HTTP headers are particularly useful for your app. For example, X-Shopify-Hmac-Sha256 is used to verify webhooks, X-Shopify-Webhook-Id is used to identify unique webhooks, and X-Shopify-Shop-Domain is used to identify the store that's associated with them.

Configuring webhooks

To receive webhooks, you register a HTTPS endpoint on your app as a webhook receiver. Then, you create a webhook subscription specifying your endpoint and the webhook topic that you wish to receive. Shopify sends your app a JSON or XML payload whenever an event for the subscribed topic occurs. The payload contains a copy of object that triggered the event.

Webhook subscriptions are scoped only to the app that they're registered to. This means that when a webhook subscription is registered to an app, other apps can't view, modify, or delete it.

If your app needs to stay in sync with Shopify, then always replace your local copy of any shop data with the webhook payload.

Webhook ordering

Webhooks are sent in order for each resource and topic combination. This means each products/update webhook for the same product is delivered in order.

However ordering is not 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.

Alternative delivery methods

Most webhook subscriptions send webhooks to an HTTPS endpoint. However, if you need to manage large volumes of event notifications, then you can configure subscriptions to send webhooks to Amazon EventBridge and Google Cloud Pub/Sub. These alternative delivery methods don't need to use HMAC to validate the payload.

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.

Best practices

This section describes some best practices for working with webhooks.

Respond to webhooks quickly

After receiving a webhook, it's important to respond to the request with a 200 OK as quickly as possible.

A common pattern is to store the payload in a message queue for later processing by a background worker. This reduces the chance of the request timing out, and the webhook delivery counting as a failure.

Recover webhooks

In the event that your app goes offline for an extended period of time, you can recover your webhook by re-registering your webhook and importing the missing data.

To re-register a webhook, consult the app's code that initially registered the webhook. You can add a check that fetches all the existing webhooks and registers only the ones that you need.

To import the missing data, you can fetch data from the outage period and feed it into your webhook processing code.

Delayed webhooks

In rare circumstances, you might experience delays in receiving webhooks. However, webhooks are always sent with the most recent data for the given resource. The payload of the delivered webhook should reflect the most recent attributes for the resource between the time of the webhook's trigger and the webhook's eventual delivery.

If receiving webhooks up to a day late might cause issues in your app, we recommend comparing the timestamp of the webhook to the current time.

Implement reconciliation jobs

Your app shouldn't rely solely on receiving data from Shopify webhooks. Because webhook delivery isn't always guaranteed, you should implement reconciliation jobs to periodically fetch data from Shopify.

Use supported filter parameters

Most query endpoints support both the created_at_min and updated_at_min filter parameters. These filters can be used to build a job that fetches all resources that have been created or updated since the last time the job ran.

Build a scalable and reliable system

Tracking traffic from Shopify's platform can be overwhelming, especially as you grow your app.

If you need to manage large volumes of event notifications to build a scalable and reliable system, then you can configure subscriptions to send webhooks to Amazon EventBridge and Google Cloud Pub/Sub.

Next steps