Shopify Webhooks: HMAC Verification, 5-Second Timeout, Retries

Shopify gives your webhook endpoint 1 second to accept the connection and 5 seconds to respond. If it doesn't get a 200-series response in time, it retries 8 times over the next 4 hours, and after 8 consecutive failures it deletes the subscription if it was created through the Admin API. Every delivery is signed in X-Shopify-Hmac-Sha256 with a base64 HMAC-SHA256 of the raw body, keyed with your app's client secret. This post collects the behavior in one table, checked against Shopify's docs on 2026-09-27, then covers the common HMAC mistakes and how to structure a handler that fits in 5 seconds.

Shopify webhook behavior at a glance

Headers on every delivery

Shopify notes that HTTP/2 often lowercases header names, so treat them case-insensitively.

Three reasons the HMAC doesn't match

HMAC failures come up again and again on Shopify's developer forum (NestJS, another thread). Almost always it's one of these:

1. The body was parsed first. Shopify's docs warn that middleware like express.json() parses the body before your verification code runs.
2. Comparing hex. The header is base64. A digest('hex') string won't match it.
3. Wrong secret. The key is the app's client secret, not a per-webhook value. Development and production apps have different client secrets.

Verifying in Node.js

Following Shopify's own example: compute a base64 HMAC over the raw body and compare in constant time.

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

const app = express();
const CLIENT_SECRET = process.env.SHOPIFY_CLIENT_SECRET!;

// Raw body for this route only; register before express.json()
app.post('/webhooks/shopify', express.raw({ type: 'application/json' }), async (req, res) => {
  const received = req.get('x-shopify-hmac-sha256') ?? '';
  const digest = crypto.createHmac('sha256', CLIENT_SECRET).update(req.body).digest('base64');

  const a = Buffer.from(digest, 'base64');
  const b = Buffer.from(received, 'base64');
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) return res.sendStatus(401);

  // Deduplicate on X-Shopify-Webhook-Id with a unique constraint
  const webhookId = req.get('x-shopify-webhook-id')!;
  const r = await db.query('INSERT INTO shopify_deliveries (id) VALUES ($1) ON CONFLICT DO NOTHING', [webhookId]);
  if (r.rowCount === 0) return res.sendStatus(200);

  await queue.add('shopify', {
    topic: req.get('x-shopify-topic'),
    shop: req.get('x-shopify-shop-domain'),
    triggeredAt: req.get('x-shopify-triggered-at'),
    body: req.body.toString('utf8'),
  });
  res.sendStatus(200); // well inside 5 seconds
});

app.use(express.json());

In NestJS, start the app with NestFactory.create(AppModule, { rawBody: true }) and read the unparsed Buffer from req.rawBody via RawBodyRequest (NestJS docs). Other frameworks are covered in getting the raw request body.

Fitting in 5 seconds

Five seconds is short compared with most providers; webhook timeouts compares them. Shopify's troubleshooting guide says to resolve timeouts by delaying processing until after you've sent the response. The handler should do four things only:

1. Verify the HMAC.
2. Drop duplicates by X-Shopify-Webhook-Id.
3. Enqueue.
4. Return 200.

Product syncs and external API calls belong in a worker. Shopify also recommends enabling Keep-Alive so connections are reused.

Planning for retries and subscription removal

Retries end 4 hours after the failure, and a subscription that fails 8 times in a row is gone. If your endpoint is down for more than about 4 hours, you lose those events and have to recreate the subscription.

• If a subscription was removed: fix the cause, recreate the subscription, and fetch current data through the Admin API to cover the gap. The missed events won't be resent.
• Reconcile regularly: Shopify says webhook delivery isn't always guaranteed and recommends reconciliation jobs that periodically fetch data from Shopify. A daily job catches gaps even when nothing looked wrong.
• Route the warning emails somewhere people read: failure warnings go to the app's emergency developer email. Use a team address.
• Check delivery status under your app's Overview and Logs in the Dev Dashboard.

Ordering

Shopify doesn't guarantee order and recommends sorting by the X-Shopify-Triggered-At header or the payload's updated_at. When updates for the same resource arrive out of order, ignore any update older than what you've stored:

UPDATE products
SET title = :title, updated_at = :updated_at
WHERE id = :id AND (updated_at IS NULL OR updated_at < :updated_at);

For more on deduplication see handling duplicate webhooks, and for debugging signatures see why webhook signature verification fails.

When you're the one sending

If your own product sends webhooks to customers or apps the way Shopify does, you need retries, signatures, delivery logs and failure alerts. Choosing a retry window is covered in designing webhook retries.

Webhook Admin provides these through an API: Standard Webhooks signatures, 8 attempts over about 28 hours by default (you can choose the number of retries and the interval per endpoint) with a 15-second timeout per attempt, and a log of every attempt with the status code and the first 1,024 bytes of the response. It alerts you (Slack, Teams, email or a webhook) when deliveries keep failing, and disables an endpoint after five days of failures until you set it back to active. The free plan includes 50,000 messages a month: https://app.webhookadmin.com/signup