How to Handle Shopify Webhooks Reliably

Webhooks are the backbone of an event-driven Shopify integration and its most common point of silent failure. A receiver that is slow, strict about ordering, or careless with duplicates will work in testing and quietly lose or corrupt data in production. This guide shows how to build one that holds up.

The documented contract

Shopify’s documentation defines how webhook delivery behaves. Design directly against these points:

Each delivery carries metadata headers including X-Shopify-Topic, X-Shopify-Webhook-Id, X-Shopify-Hmac-Sha256, X-Shopify-Shop-Domain, and X-Shopify-Triggered-At.

Step 1: Get the raw body

HMAC verification must run over the exact bytes Shopify sent. If your framework parses JSON first and you re-serialize it, whitespace and key order can change and the signature will not match.

In Express, mount a raw body parser only on the webhook route:

import express from 'express';
const app = express();

// Raw bytes for webhooks only; JSON parsing elsewhere.
app.post('/webhooks/shopify', express.raw({ type: 'application/json', limit: '2mb' }), handleWebhook);
app.use(express.json());

In other runtimes, read the request body as an ArrayBuffer or bytes before any parsing.

Step 2: Verify the signature

Compute an HMAC-SHA256 of the raw body using your app’s client secret, base64-encode it, and compare it to the header with a constant-time comparison:

import crypto from 'node:crypto';

function verifyShopifyHmac(raw: Buffer, header: string | undefined, secret: string): boolean {
  if (!header) return false;
  const expected = crypto.createHmac('sha256', secret).update(raw).digest('base64');
  const a = Buffer.from(expected, 'utf8');
  const b = Buffer.from(header, 'utf8');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Return 401 for invalid signatures and log the attempt (without the body). During secret rotation, accept either the old or new secret for a short, defined window.

Step 3: Store, then acknowledge

Write the event to durable storage and respond immediately. Use the webhook ID as a unique key so retries and duplicates collapse into one row:

async function handleWebhook(req: express.Request, res: express.Response) {
  if (!verifyShopifyHmac(req.body, req.get('X-Shopify-Hmac-Sha256'), process.env.SHOPIFY_CLIENT_SECRET!)) {
    return res.sendStatus(401);
  }
  try {
    await db.query(
      `INSERT INTO inbound_events (webhook_id, shop, topic, triggered_at, payload)
       VALUES ($1, $2, $3, $4, $5::jsonb)
       ON CONFLICT (webhook_id) DO NOTHING`,
      [
        req.get('X-Shopify-Webhook-Id'),
        req.get('X-Shopify-Shop-Domain'),
        req.get('X-Shopify-Topic'),
        req.get('X-Shopify-Triggered-At'),
        req.body.toString('utf8'),
      ],
    );
    return res.sendStatus(200);
  } catch (err) {
    // Storage failed: let Shopify retry rather than acknowledging an event we did not keep.
    logger.error({ err }, 'failed to persist webhook');
    return res.sendStatus(500);
  }
}

The one situation where you should not return 200 is when you failed to store the event. A 5xx tells Shopify to retry; a 200 for an unstored event loses it permanently.

Step 4: Process asynchronously

A worker reads stored events and processes them. Three rules keep processing correct regardless of delivery order:

1. Treat the webhook as a notification. Extract the resource ID and fetch the current resource from the GraphQL Admin API. If two updates arrive out of order, both fetches return the latest state.
2. Skip stale work. Store the updatedAt of the last version you wrote for each resource. If a fetched resource is not newer, mark the event done without writing.
3. Serialize per resource. Ensure two workers do not process the same order simultaneously. See the architecture guide for locking options.

Step 5: Watch for failures and removed subscriptions

Because Shopify removes subscriptions after persistent failures, a receiver outage can silently end your integration. Protect against it:

• Alert on delivery failure rates. Shopify’s developer dashboard shows webhook delivery metrics; Shopify’s troubleshooting guide flags failure rates above 0.5% as higher than average.
• Alert on response time. Shopify lists response times between four and five seconds as a symptom to fix.
• Verify subscriptions on a schedule. A daily job that lists your webhook subscriptions through the API and recreates missing ones is cheap insurance.
• Alert on silence. If a store that normally receives orders every few minutes has not sent orders/create for an hour during business hours, something is wrong.

Step 6: Reconcile

Even a perfect receiver can miss events — during a deployment, a DNS problem, or a regional outage. Run a scheduled query for resources updated since the last checkpoint and enqueue anything not already processed. The webhooks vs. polling guide shows how to combine both approaches.

Alternative delivery targets

Instead of HTTPS, Shopify can deliver webhooks to Amazon EventBridge or Google Cloud Pub/Sub. This removes the need to operate a public receiver and the five-second response concern, since the cloud service accepts the event. You still need consumers that deduplicate, fetch current state, and handle failures.

Security considerations

• Reject unsigned or invalid requests before any parsing or database work.
• Use HTTPS only, and keep the endpoint path unguessable as defense in depth (not as a replacement for HMAC).
• Rate-limit the endpoint at the edge to absorb abuse without affecting legitimate deliveries.
• Limit request body size.
• Treat payloads as untrusted input: validate types before using values in queries.
• Restrict access to stored payloads, which may contain customer personal data.

Testing

• Unit test HMAC verification with a stored real payload and its header, plus a tampered body.
• Send the same payload twice and confirm one stored row.
• Deliver an older update after a newer one and confirm the newer state wins.
• Make the database unavailable and confirm the receiver returns 5xx.
• Measure p99 response time under a burst of deliveries; it should stay far below five seconds.
• Use Shopify CLI’s webhook trigger command or a development store to send test events end to end.

Common mistakes

• Parsing JSON before verifying the HMAC.
• Doing ERP calls or Shopify API calls inside the request.
• Returning 200 even when storing the event failed.
• Using the payload order to decide which version is newer.
• No monitoring of subscription health until orders stop arriving.

Summary

A reliable webhook receiver verifies the HMAC on the raw body, stores the event under its webhook ID, and responds quickly — and nothing else. Processing happens later, fetches current data, skips stale versions, and runs one resource at a time. Monitor delivery failures and subscription health, and reconcile on a schedule, because Shopify documents that webhooks alone are not a guarantee.