Shopify webhooks

How to Test Shopify Webhooks (and Verify X-Shopify-Hmac-Sha256)

Shopify notifies apps about orders, products, customers and carts through webhooks. They are strict about response time and unforgiving about body handling.

Capture a real Shopify webhook in a minute

  1. Get a URL. Use the button on this page. It opens the inspector with a fresh URL that is ready to receive.
  2. Give it to Shopify. Subscribe to a topic from your app configuration or the Admin API, or for a quick test use Settings → Notifications → Webhooks in the store admin, which also has a Send test notification button.
  3. Trigger an event. The request appears in the inspector as it arrives, with Shopify recognised and the event name shown.
  4. Check the signature. Open Verify signature, paste your secret and confirm the request is genuine. The check runs in your browser.

Headers Shopify sends

HeaderMeaning
X-Shopify-TopicThe event, such as orders/create or products/update.
X-Shopify-Hmac-Sha256Base64-encoded HMAC-SHA256 of the raw body.
X-Shopify-Shop-DomainThe store that sent it, such as example.myshopify.com.
X-Shopify-Webhook-IdIdentifies the delivery. Useful for spotting duplicates.
X-Shopify-API-VersionThe API version the payload was serialised with.
X-Shopify-Triggered-AtWhen the event happened.

Verifying the HMAC

Shopify signs the raw body with your app's client secret. Unlike Stripe and GitHub, the digest is base64, not hex.

Verifying X-Shopify-Hmac-Sha256 (Node.js)
import crypto from "node:crypto";

export function verifyShopify(rawBody, header, clientSecret) {
  const expected = crypto
    .createHmac("sha256", clientSecret)
    .update(rawBody)
    .digest("base64");

  const received = header ?? "";
  return received.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
}
Hex versus base64If your computed value is 64 characters of hex and Shopify's is 44 characters ending in =, you are comparing two encodings of what may be the same digest. Encode as base64 before comparing.

What Shopify expects back

  • A 2xx response within five seconds. Shopify treats anything slower as a failure, so acknowledge first and process afterwards.
  • Retries. Failed deliveries are retried with a backoff. A subscription that keeps failing can be removed, so watch for sustained errors. Check Shopify's documentation for the current schedule.
  • Duplicates. The same event can be delivered more than once. Use the ID headers to make processing idempotent.

Test the slow-endpoint case deliberately

Give your webhook.stream URL a response delay of six seconds, send a test notification and watch what Shopify does. It is far better to learn how timeouts behave here than from a production incident.

Frequently asked questions

Which secret does Shopify use to sign webhooks?

For app webhooks, the app's client secret (API secret key). Webhooks created in the store admin under Notifications are signed with the key shown on that page.

Why is my Shopify HMAC different from the header?

Check three things: you are hashing the raw body bytes, you are using the correct secret, and you are comparing base64 to base64. Shopify sends base64, not hex.

How fast must I respond to a Shopify webhook?

Within five seconds, with a 2xx status. Do the real work asynchronously.