Webhooks

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.

Requirements

  • You're authenticated with the GraphQL Admin API or REST Admin API.

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, register a HTTPS endpoint on your app as a webhook receiver. Then, create a webhook subscription specifying your endpoint and the webhook topic that you wish to receive. Shopify will send 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.

1. Subscribe to a webhook topic

You can subscribe to a webhook topic by running the webhookSubscriptionCreate mutation in GraphQL or by sending a POST request to the Webhook resource in REST.

The following examples show how to subscribe your app to the orders/create webhook topic.

2. Test a webhook

If you're a Shopify Partner, then you can create a development store to test a webhook.

To test a webhook, run a local server or use a publicly available service such as Beeceptor.

If you decide to run a server locally, then you need to make it publicly available using a service such as Pagekite or ngrok. The following URLs can't be endpoints for a webhook:

  • Localhost
  • Any URL ending in the word "internal". For example, thisshop.com/internal
  • Domains like www.example.com
  • Shopify domains such as shopify.com and myshopify.com

3. Register an endpoint

Your endpoint must be an HTTPS webhook address with a valid SSL certificate that can correctly process event notifications. You must also verify your webhook to make sure webhook requests originate from Shopify.

Payloads contain a JSON or XML object with the data for the webhook event. The contents and structure of each payload varies on the subscribed topic. For more information about webhook topics, refer to the REST Webhook resource or the GraphQL WebhookSubscription object.

4. Receive a webhook

After you register an endpoint, Shopify sends an HTTP POST request to the URL specified every time that event occurs. The request's POST parameters contain the JSON or XML data relevant to the event that triggered the request.

Shopify verifies SSL certificates when delivering payloads to HTTPS webhook addresses. Make sure your server is correctly configured to support HTTPS with a valid SSL certificate.

5. Respond to a webhook

Your webhook acknowledges that it received data by sending a 200 OK response. Any response outside of the 200 range, including 3XX HTTP redirection codes, indicates that you didn't receive the webhook. Shopify doesn't follow redirects for webhook notifications and considers them to be an error response.

Frequency of retries

Shopify has implemented a five-second timeout period and a retry period for webhook subscriptions.

Shopify waits five seconds for a response to each request to a webhook. If there's no response, or an error is returned, then Shopify retries the connection 19 times over the next 48 hours. If there are 19 consecutive failures, then the webhook subscription is automatically deleted. A warning that the subscription will be deleted is sent to the app's emergency developer email address.

To avoid timeouts and errors, consider deferring app processing until after the webhook response has been successfully sent.

If you're having trouble diagnosing the cause of webhook failures, the webhook deliveries dashboard contains more information about how your webhooks are performing.

6. Verify a webhook

Webhooks can be verified by calculating a digital signature. Each webhook request includes a base64-encoded X-Shopify-Hmac-SHA256 header, which is generated using the app's shared secret along with the data sent in the request.

Verify the request is from Shopify

To verify that the request came from Shopify, compute the HMAC digest according to the following algorithm and compare it to the value in the X-Shopify-Hmac-SHA256 header. If they match, then you can be sure that the webhook was sent from Shopify. As a best practice, the HMAC digest should be verified before the app responds to the webhook.

Manage webhook API versions

Like the majority of Shopify’s APIs, webhook resources are versioned. Make sure your code is updated regularly to use a supported webhook version.

1. Update your code

Before you select a newer webhook API version, you need to test it against your code.

Add logic to your code so that it handles webhooks differently depending on their API version. To check the API version, your app can use the X-Shopify-Api-Version request header in every webhook POST request.

2. Test the newer API version

From your store's notification settings, add some webhooks that use the newer version, and then send some test payloads. Your existing webhooks will continue to use the older API version. Check that your code correctly handles the test webhooks, and make any necessary adjustments.

Select a webhook API version for Shopify admin notifications

  1. From the Shopify admin, go to Settings > Notifications.
  2. Click Create webhook, or click an existing webhook.
  3. If this is a new webhook, then enter the event, format, and URL.
  4. Select an API version from the Webhook API version drop-down list.
  5. Click Save webhook.

3. Select the newer API version

Select the newer API version for your public, custom, or private app. Your updated webhook will now use this version.

Select a webhook API version for a public or custom app

  1. From your Partner Dashboard, go to Apps.
  2. Click the app that you want to update.
  3. Click App setup.
  4. In the Event subscriptions section, select an API version from the Event version drop-down list.
  5. Click Save.

Select a webhook API version for a private app

  1. From the Shopify admin, go to Apps.
  2. Click Manage private apps.
  3. Click the private app that you're updating.
  4. In the Admin API section, select an API version from the Webhook API version drop-down list.
  5. Click Save.

4. Test webhooks and remove references to the older API version

Make sure that your code handles the updated webhook payloads correctly. After you've verified that everything is working, update your code to remove the logic that you added and all the references to the old webhook API 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