Configuring webhooks

This tutorial shows you how to subscribe to a webhook topic, test a webhook, register an endpoint, receive and respond to a webhook, and verify a webhook.

Requirements

  • You're familiar with how webhooks work.
  • You're authenticated with the GraphQL Admin API or REST Admin API.

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.

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

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.

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.

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.

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.

Next steps