Skip to content
HookDeploy

Shopify webhooks

Last verified against Shopify's documentation on September 27, 2026.

On this page ↓

Shopify sends webhooks when something happens in a store your app is installed on: an order is placed, a product changes, inventory moves, the app is uninstalled. Most delivery problems come from a few causes: a handler slower than Shopify’s 5-second limit, an HMAC check running against a parsed body or the wrong secret, and repeated failures that lead Shopify to remove the subscription entirely. This page covers what Shopify sends, how it delivers, how to fix the common errors, and where HookDeploy fits.

What Shopify sends webhooks for

Shopify organizes webhooks into topics named resource/action. These are the ones most apps depend on.

AreaKey topicsTypical use
Ordersorders/create, orders/paid, orders/updated, orders/cancelled, orders/fulfilledSync orders to an ERP, trigger fulfillment, send notifications
Fulfillment and refundsfulfillments/create, refunds/createUpdate shipping systems, reconcile refunds
Products and inventoryproducts/create, products/update, products/delete, inventory_levels/updateKeep catalogs and stock levels in sync with other channels
Customerscustomers/create, customers/updateSync CRM and email marketing lists
Checkouts and cartscheckouts/create, checkouts/update, carts/updateAbandoned-cart flows and analytics
App lifecycleapp/uninstalled, app_subscriptions/updateClean up when a merchant uninstalls, track billing changes
Mandatory compliancecustomers/data_request, customers/redact, shop/redactRequired for every app in the Shopify App Store

Each payload is the full resource as JSON, serialized with the API version in the X-Shopify-API-Version header. Two subscription options cut noise: filter limits which changes trigger a delivery, and include_fields trims the payload to the fields you need.

Shopify can deliver to HTTPS, Google Cloud Pub/Sub, or Amazon EventBridge. This page covers HTTPS delivery.

How Shopify delivers webhooks

BehaviorDetail
Signature headerX-Shopify-Hmac-Sha256: a base64-encoded HMAC-SHA256 of the raw request body, keyed with your app’s client secret
Timestamp in signatureNone. The signature doesn’t expire
Other headersX-Shopify-Topic, X-Shopify-Shop-Domain, X-Shopify-API-Version, X-Shopify-Webhook-Id (unique per delivery), X-Shopify-Event-Id (shared across subscriptions for one merchant action), X-Shopify-Triggered-At
Header caseVaries. HTTP/2 often lowercases header names, so treat them as case-insensitive
Timeouts1 second to connect, 5 seconds for the whole request
SuccessAny 2xx. Everything else, including 3xx redirects, is a failure
Retries8 times over 4 hours with exponential backoff, using the original payload
Subscription removalAfter 8 consecutive failures, subscriptions created through the Admin API are deleted and the app’s emergency developer email gets a warning
OrderingNot guaranteed, within a topic or across topics
DelaysDeliveries can arrive late, up to a day in some cases
DuplicatesPossible, for example after a timeout or retry
Source IPsNot published
Secret rotationAfter you rotate your app’s client secret, it can take up to an hour before Shopify signs with the new one

Common Shopify webhook errors and how to fix them

Timeouts and response times over 4 seconds

Shopify gives your server 1 second to accept the connection and 5 seconds to finish responding. Shopify’s own troubleshooting guidance flags response times between four and five seconds as a problem, because they’re one slow database call away from failing. Verify the HMAC, return 200, and process the payload from a queue.

HMAC verification fails

If you’re sure the delivery came from Shopify but the check fails:

  • The body was parsed first. Shopify signs the raw bytes. If express.json() or another body parser runs before your verification, the body is re-serialized and the HMAC won’t match. Put your raw-body webhook route ahead of any global parsing middleware.
  • Wrong secret. The key is your app’s client secret. If you rotated it recently, Shopify can keep signing with the old secret for up to an hour.
  • Comparing the wrong way. The header is base64. Compute a base64 digest, or decode both values before comparing, and use a constant-time comparison.
  • Header lookups by exact case. X-Shopify-Hmac-Sha256 might arrive as x-shopify-hmac-sha256. Read headers case-insensitively.
  • Encoding. Make sure your framework isn’t transcoding the body before you hash it.

App review fails “Verifies webhooks with HMAC signatures”

Shopify’s automated app check sends the mandatory compliance topics, customers/data_request, customers/redact, and shop/redact, including requests with an invalid HMAC, and requires a 401 Unauthorized response for those. A 200, 405, or any other status fails the check. Your compliance endpoint must verify the HMAC itself and return 401 when it doesn’t match.

Subscription removed

After repeated failures, Shopify deletes subscriptions created through the Admin API, and new events stop arriving entirely. Fix the underlying problem, then recreate the subscriptions. Subscriptions declared in your app configuration (shopify.app.toml) don’t need to be recreated. Then backfill what you missed by fetching the outage period from the Admin API.

“Delivery failed after retries”

Shopify stops after 8 attempts over about 4 hours. Those events won’t be sent again. Recover them by querying the Admin API for the affected time range and running the results through your normal processing code.

Redirects (3xx)

Shopify treats every redirect as a failed delivery. The usual causes are HTTP to HTTPS redirects, www redirects, and trailing-slash rewrites. Register the final URL exactly as your server serves it.

Stale data on retries

Retries deliver the original payload from when the event was triggered, not the resource’s current state. If a retry arrives hours later, its data may be out of date. Compare X-Shopify-Triggered-At or the resource’s updated_at against what you’ve already stored, or fetch the latest state from the Admin API.

Retries going to an old URL

Retries go to the address the subscription had when the event was triggered. Changing the subscription’s URL during an outage doesn’t redirect webhooks already in their retry cycle.

Out-of-order and late deliveries

A products/update can arrive before the matching products/create, and some deliveries arrive late. Don’t rely on arrival order. When order matters, compare timestamps, or fetch the resource from the Admin API.

Why use HookDeploy with Shopify

Keep your subscriptions alive

The most expensive Shopify failure isn’t one lost delivery. It’s a subscription Shopify removes after repeated failures, after which new orders and product changes silently stop arriving.

HookDeploy captures each delivery at Cloudflare’s edge and responds to Shopify well inside its 1-second connection and 5-second request limits, before forwarding to your server. A slow handler, a deploy, or an outage on your side no longer counts as a failed delivery, so it can’t cost you the subscription. From there:

  • Destination retries. Starter retries 3 times (after 30 seconds, 5 minutes, and 30 minutes). Pro and Scale retry up to 5 times on a schedule you choose. Free doesn’t retry automatically.
  • Incidents. Forward failures are grouped into incidents, and you can bulk-replay them at a controlled rate once your server recovers.
  • Longer recovery window. Shopify stops retrying after about 4 hours. HookDeploy keeps captured deliveries for your plan’s retention period, from 7 days on Free to 365 days on Enterprise, and any of them can be replayed.

HMAC verification works on every retry and replay

On first delivery, HookDeploy forwards Shopify’s original body and X-Shopify-Hmac-Sha256 header unchanged. That header is on HookDeploy’s protected list: it’s never redacted from stored requests, and custom header strip rules can’t remove it.

Shopify’s HMAC has no timestamp, so a delivery retried an hour later or replayed a week later still verifies. Two things do break it:

  • Transformations. A transformation changes the body, so the HMAC won’t match at that destination. Use transformations for destinations that don’t verify Shopify’s HMAC, such as analytics or internal tools, and protect those with an injected auth header.
  • Privacy filters. Retries and replays send the stored copy of the request. If a privacy filter or body key sanitization changed what was stored, the HMAC won’t match.

One subscription, many destinations

Send each Shopify delivery to your app, an ERP, a warehouse system, and a Slack channel in parallel, from a single subscription. A failing destination doesn’t hold up the others. Free includes 1 destination per endpoint, Starter includes 5, and Pro and above are unlimited.

Deliver to systems Shopify can’t reach

Shopify needs a public HTTPS URL, but ERPs, warehouse systems, and point-of-sale backends often sit on private networks. The HookDeploy Agent connects outward from your network over mTLS and delivers to a local port, so Shopify webhooks reach them with no public IP, open port, or exposed route.

Develop against real store traffic

A tap sends a temporary copy of live deliveries from a development store to 127.0.0.1 on your machine, and you can replay any captured delivery to your local handler. You don’t need to place a new test order every time you want a fresh orders/create.

Know the limits

  • Mandatory compliance webhooks. Don’t route customers/data_request, customers/redact, or shop/redact through HookDeploy. App review requires a 401 for an invalid HMAC, and HookDeploy acknowledges every request it captures. Register those topics directly with your app.
  • Payload size. HookDeploy accepts payloads up to 256 KB on Free, 1 MB on Starter, 25 MB on Pro and Scale, and 100 MB on Enterprise. A larger payload gets a 413, which Shopify counts as a failed delivery. Large orders with many line items are the usual culprit, so use include_fields to trim payloads to what you need.
  • Plan limits. On Free, requests beyond the monthly allowance get a 429, which Shopify also counts as a failure. Paid plans keep accepting traffic past the included volume.
  • No IP allowlist. Shopify doesn’t publish webhook IP addresses, and it can’t send HookDeploy’s secret token as a header. Verify the HMAC in your handler.

Retries, replays, and duplicates

Because Shopify’s HMAC doesn’t expire, retries and replays from HookDeploy verify exactly like the original delivery. The things to get right are duplicates and freshness.

HookDeploy forwards Shopify’s original headers, including X-Shopify-Webhook-Id and X-Shopify-Event-Id. Use them the way Shopify intends:

  • X-Shopify-Webhook-Id identifies a single delivery. Record each one you’ve processed and skip repeats, whether they come from a Shopify retry or a HookDeploy retry or replay.
  • X-Shopify-Event-Id is shared by every delivery from the same merchant action, across all your subscriptions for that topic. Use it to correlate them.

A replay carries the payload from when the event was triggered. Before acting on an old delivery, check X-Shopify-Triggered-At or updated_at against your stored state. If your handler rejects deliveries older than some cutoff, allow for retries and replays when you set it.

To reprocess an event on purpose, for example after fixing a bug, clear its webhook ID from your processed list before replaying it.

Set up Shopify with HookDeploy

  1. In HookDeploy, create an endpoint (for example, Shopify production) and copy its URL.
  2. In your app’s shopify.app.toml, subscribe your topics to the HookDeploy URL, and register the mandatory compliance topics directly with your app:
[webhooks]
api_version = "2026-04"

  [[webhooks.subscriptions]]
  topics = ["orders/create", "orders/paid", "app/uninstalled"]
  uri = "https://hookdeploy.dev/h/YOUR_SLUG"

  # Compliance topics must verify HMAC and return 401 themselves,
  # so they go straight to your app, not through HookDeploy.
  [[webhooks.subscriptions]]
  compliance_topics = ["customers/data_request", "customers/redact", "shop/redact"]
  uri = "https://your-app.example.com/webhooks/compliance"
  1. Deploy the configuration with shopify app deploy.
  2. In HookDeploy, add a forward destination pointing to your handler, or to an agent for private delivery, and set its retries.
  3. Trigger a real event in a development store, such as creating a product or placing a test order, and confirm the delivery appears in HookDeploy and reaches your handler.

Example handler (Node.js and Express)

import crypto from 'node:crypto';
import express from 'express';

const app = express();

// Raw body parser on this route, registered before any global JSON middleware.
app.post('/webhooks/shopify', express.raw({ type: 'application/json' }), async (req, res) => {
  const received = Buffer.from(req.get('x-shopify-hmac-sha256') ?? '', 'base64');
  const expected = crypto
    .createHmac('sha256', process.env.SHOPIFY_CLIENT_SECRET)
    .update(req.body)   // raw bytes, untouched
    .digest();

  const valid =
    received.length === expected.length &&
    crypto.timingSafeEqual(received, expected);
  if (!valid) return res.status(401).send('Unauthorized');

  res.sendStatus(200);  // respond well inside Shopify's 5 seconds
  await enqueue({
    webhookId: req.get('x-shopify-webhook-id'),  // skip IDs you've already handled
    topic: req.get('x-shopify-topic'),
    shop: req.get('x-shopify-shop-domain'),
    triggeredAt: req.get('x-shopify-triggered-at'),
    payload: JSON.parse(req.body.toString('utf8')),
  });
});

FAQ

Does HookDeploy break Shopify HMAC verification?

No. HookDeploy forwards Shopify's original body and X-Shopify-Hmac-Sha256 header unchanged. Shopify's signature has no timestamp, so retries and replays verify too, however late they arrive. Verification fails only when a transformation changes the body, or when a privacy filter changed the stored copy used for retries and replays.

Can I point Shopify's mandatory compliance webhooks at HookDeploy?

No. Shopify's app review sends compliance webhooks with an invalid HMAC and expects your endpoint to return 401 Unauthorized. HookDeploy acknowledges every request it captures, so a compliance subscription pointed at HookDeploy would fail that check. Register the compliance topics directly with your app, and use HookDeploy for your other topics.

Will HookDeploy stop Shopify from removing my webhook subscriptions?

Yes, as long as HookDeploy captures the delivery. Shopify removes subscriptions after repeated failed deliveries, and HookDeploy responds to Shopify right away even when your server is down. The exception is a request HookDeploy rejects before capture, such as a Free plan that has used its monthly allowance, which Shopify counts as a failure.

How do I secure a HookDeploy endpoint for Shopify?

Verify the HMAC in your handler. Shopify doesn't publish fixed webhook IP addresses, so an IP allowlist isn't an option, and Shopify can't add HookDeploy's secret token as a header. HMAC verification is the protection Shopify designed for this.

Can I receive Shopify webhooks on localhost?

Yes. Point your subscription at HookDeploy, then start a tap from the Desktop Agent or CLI to copy live deliveries to a local port, or replay a captured delivery to your local handler. Your laptop never needs a public URL.

Should I use Google Pub/Sub or Amazon EventBridge instead?

Shopify recommends them for high-volume apps, and they handle HMAC verification and delivery timing for you. HookDeploy is for HTTPS delivery, when you want to inspect every payload, replay deliveries, fan them out to several destinations, or deliver to a server with no public URL.

Capture Shopify webhooks free

Start free