Shopify Webhooks: Setup, Verification, and Common Pitfalls

Shopify webhooks look similar to Stripe or GitHub's at first glance: HMAC-signed HTTP POST requests. The details diverge quickly once you start building against them. The signature encoding is different, subscriptions work per-topic rather than per-webhook, and public apps carry mandatory compliance requirements that have nothing to do with the app's actual functionality.

This guide covers what's specific to Shopify.

Topics, not one webhook for everything

GitHub lets you pick from a checkbox list of events on a single webhook. Shopify instead treats each event type, called a topic, as its own subscription.

orders/create
orders/updated
orders/cancelled
products/create
products/update
customers/create
app/uninstalled

You can point every topic at the same URL. Route based on the X-Shopify-Topic header once the request lands, rather than registering a different endpoint per topic.

shopify app webhooks trigger --topic=orders/create

Verifying the signature

Shopify signs the raw request body with your app's client secret, using HMAC-SHA256, and base64-encodes the result into the X-Shopify-Hmac-SHA256 header. If you're coming from GitHub or Stripe, the algorithm is the same but the encoding isn't: those use hex, Shopify uses base64. Reusing verification code without changing the encoding is a common first bug.

import { createHmac, timingSafeEqual } from 'crypto';

function verifyShopifyWebhook(
  rawBody: Buffer,
  hmacHeader: string | undefined,
  secret: string
): boolean {
  if (!hmacHeader) return false;

  const expected = createHmac('sha256', secret)
    .update(rawBody)
    .digest('base64');

  try {
    return timingSafeEqual(
      Buffer.from(hmacHeader),
      Buffer.from(expected)
    );
  } catch {
    return false;
  }
}

The 5-second window

Shopify expects a response within 5 seconds, tighter than GitHub's 10 or Stripe's 20. If your endpoint doesn't respond in time, or returns an error, Shopify retries 8 times over the next 4 hours, with most attempts front-loaded into the first half hour.

app.post('/webhooks/shopify', async (req, res) => {
  const topic = req.headers['x-shopify-topic'] as string;
  const hmac = req.headers['x-shopify-hmac-sha256'] as string;

  if (!verifyShopifyWebhook(req.rawBody, hmac, process.env.SHOPIFY_CLIENT_SECRET!)) {
    return res.status(401).send('Invalid signature');
  }

  // Acknowledge immediately
  res.status(200).send('ok');

  // Process asynchronously, well outside the 5-second window
  void processShopifyWebhook(topic, req.body);
});

Anything beyond a fast, guaranteed-quick database write belongs in the async path. A slow handler and a broken one produce identical retry behaviour from Shopify's side.

Deduplication: use the delivery ID, not the payload

Shopify includes an X-Shopify-Webhook-Id header, a UUID unique to each delivery attempt, on every request. Store it and check for it before processing:

async function processShopifyWebhook(topic: string, payload: unknown, deliveryId: string) {
  const seen = await db.processedWebhooks.findUnique({ where: { deliveryId } });
  if (seen) return; // Already handled, e.g. a retry after a timeout

  await db.processedWebhooks.create({ data: { deliveryId, topic } });
  // ... handle the event
}

Retries during the 4-hour window will reuse the same delivery ID, so this catches the most common source of duplicate processing without needing to hash the payload.

Compliance webhooks: mandatory for public apps

If you're building a public app for the Shopify App Store, three topics are non-negotiable regardless of what your app actually does:

• customers/data_request - a merchant's customer has requested their data; you must respond with what you hold on them
• customers/redact - a merchant's customer has requested deletion; you must erase their data within 30 days
• shop/redact - a merchant has uninstalled your app and 48 hours have passed; erase their shop's data

Shopify sends these automatically to every registered app; you don't request them. App review checks that all three return a 200 and are handled correctly, even for an app that stores nothing about individual customers. In that case, the handler can be a no-op that still returns 200, but it has to exist.

Common failure patterns

"HMAC verification passes in Postman but fails from Shopify"

Almost always a body-parsing issue: something in the request pipeline (a proxy, a global JSON middleware) is altering the bytes before your verification code sees them. Use a raw body parser scoped to the webhook route only.

"Webhook fires once per order but I'm seeing it twice"

Check whether you're deduplicating on X-Shopify-Webhook-Id. A retry after a slow response looks, from your database's perspective, exactly like a second genuine order unless you're checking the delivery ID first.

"App review rejected for compliance webhooks"

The most common cause is one of the three topics returning a non-200, often because the handler throws on shops that have no data to redact. Make sure all three succeed even in the empty case.

Shopify's per-topic subscriptions and base64 HMAC are the two things that catch people coming from other providers. Once those are handled, the rest (fast acknowledgment, async processing, dedup on delivery ID) is the same pattern that works for any webhook source.

If you're connecting Shopify to Webhook Watchtower, the Shopify setup guide covers the built-in preset: it selects the base64 HMAC algorithm automatically and deduplicates on X-Shopify-Webhook-Id, so a retried delivery never reaches your endpoint twice.