All Tutorials

Manage webhooks with the Admin API

All Tutorials

Manage webhooks with the Admin API

Manage webhooks with the Admin API

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

To create a webhook, you register both an HTTP endpoint on your app as a webhook receiver and an event that triggers a request to that endpoint. Shopify sends you a JSON or XML payload when your selected event occurs, with a copy of the relevant object.

Data about orders, products, or customers can change often, and receiving webhooks is much more efficient than continuously polling for changes to every resource. If your app needs to stay in sync with Shopify, then always replace your local copy of any shop data with the webhook payload.

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

Configuring webhooks

You can configure a webhook using the API or in the Shopify admin. Webhooks created using the API do not show up in the admin.

Configure a webhook using the API

You can configure a webhook by making an HTTP POST request to the Webhook resource in the REST Admin API.

Configure a webhook using the Shopify admin

If you are developing an app for a specific shop, then you can configure your webhooks using the Shopify admin:

  1. In the Webhooks section, click Create a webhook.

  2. Select the event type you want to listen for, the format (JSON or XML), and the URL where you want to receive notifications.

After you've created a webhook, you're presented with a secret to validate its integrity. You can also test it.

Testing webhooks

When testing webhooks, you can 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 do not work as endpoints for webhooks:

  • 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

Testing webhooks configured using the Shopify admin

To test your webhook from the Shopify admin:

  1. Go to the Webhooks section of the Notifications screen.
  2. Click Send test notification next to the webhook that you want to test.

An example webhook is sent to the configured webhook URL.

Creating an endpoint for webhooks

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

Payloads

Payloads contain a JSON or XML object with the data for the webhook event. The contents and structure of each payload varies depending on the subscribed event.

Receiving a webhook

After you register a webhook URL, Shopify issues an HTTP POST request to the URL specified every time that event occurs. The request's POST parameters contain XML/JSON 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.

Responding 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 did not receive the webhook. Shopify does not follow redirects for webhook notifications and considers them to be an error response.

Frequency

Shopify has implemented a five second timeout period and a retry period for subscriptions. Shopify waits five seconds for a response to each request to a webhook. If there is 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.

Verifying webhooks

Webhooks created through the API by a Shopify App are 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.

Webhooks created through the Shopify admin are verified using the secret displayed in the Webhooks section of the Notifications screen.

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.

Best practices

This section contains some procedures to ensure your webhook integration functions as seamlessly as possible.

Recovering webhooks

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

Re-registering webhooks

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

Importing missing data

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

Duplicate webhooks

To guard against webhook duplication and flooding, Shopify uses webhook de-duplication. This reduces the total amount of webhooks when multiple update actions are performed against an API resource in rapid succession. De-duplication ensures that only one webhook is generated per 10-second window of time, even if multiple update actions occur within that window. The webhook that is issued after 10 seconds contains the most up-to-date payload.

For example, if a product is created and then updated multiple times within 10 seconds, only two webhooks are generated. The first webhook reports the webhook create event, and the second webhook reports the latest state of the object after ten seconds. You can also guard against duplicate webhook events by making your webhook processing behavior idempotent.