HTTPS webhook delivery

• You're familiar with how webhooks work.

• You're familiar with the webhooks best practices.

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

• You're a Shopify Partner.

• You've created a development store for testing webhooks.

Your endpoint must be an HTTPS webhook address with a valid SSL certificate that can correctly process event notifications.

Payloads contain a JSON object with the data for the webhook event. The contents and structure of each payload varies by the subscribed topic. Refer to the REST Webhook resource or the GraphQL WebhookSubscription object for more information.

Subscribe to a webhook topic by doing one of the following:

• Run the webhookSubscriptionCreate mutation in GraphQL

• Send a POST request to the Webhook resource in REST

• You create mandatory webhooks only either via the Partner Dashboard or by updating the app config TOML.

For example, the following requests subscribe an app to the orders/create webhook topic.

1. Run a local server or use a publicly-available service such as Beeceptor.

2. If you're running a local server, then make it publicly available using a service like Pagekite or ngrok.

3. Trigger your webhook. You can trigger a webhook manually using the Shopify CLI webhook trigger command, or by performing the related action in a store that has your app installed. Manually triggering webhooks doesn't test your webhook subscriptions.

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

Before you respond to a webhook, you need to verify that the webhook was sent from Shopify. You can verify the webhook by calculating a digital signature.

Each webhook request includes a base64-encoded X-Shopify-Hmac-SHA256 header, which is generated using the app's client secret along with the data sent in the request. If you're using PHP, or a Rack-based framework such as Ruby on Rails or Sinatra, then the header is HTTP_X_SHOPIFY_HMAC_SHA256.

1. Compute the HMAC digest according to the following algorithm:

2. Compare the computed value to the value in the X-Shopify-Hmac-SHA256 or HTTP_X_SHOPIFY_HMAC_SHA256 header.

   If the HMAC digest and header value match, then the webhook was sent from Shopify.

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.

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 Shopify can't establish a connection to your server after one second, then Shopify will timeout before the expected five seconds.

After receiving a webhook using an HTTPS endpoint, it's important to respond to the request with a 200 OK within one to two seconds. There's a five-second timeout for the entire request, and the webhook delivery system expects to establish the connection in less than one second or the request times out.

You can install a package like Better Que to store the webhook payload in a queue to process later. This enables your app to respond quickly, and your job can take as long as it needs to complete.

The webhook delivery system uses HTTP Keep-Alive to reuse connections to the same host and endpoint. This reduces network congestion and the latency in subsequent requests. Ensure that you have Keep-Alive enabled for your endpoint to reduce the overhead of receiving concurrent requests.

To prepare your endpoint for a burst of requests, decouple webhook processing from request responses. 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 having the webhook delivery count as a failure. Storing the webhook and responding immediately ensures that your system is resilient to a high volume of requests.

• Set up the mandatory webhooks for apps distributed through the Shopify App Store.

• Test your configuration by manually triggering a webhook delivery using the Shopify CLI webhook trigger command. Manually triggering webhooks doesn't test your webhook subscriptions.

• Learn how to manage webhooks for different API versions.

• Learn about the available topics for REST Admin API webhooks.

• Learn about the available topics for GraphQL Admin API webhooks.