Shopify webhooks

Capture Shopify webhooks and see why the 5-second timeout keeps failing them.

Get a test URL

claude mcp add --transport http webhook-studio https://webhook-studio.com/mcp \
  --header "Authorization: Bearer $(curl -s -X POST https://webhook-studio.com/api/start | jq -r .api_token)"

Point Shopify at this URL

1. Create a test endpoint below and copy its URL.
2. For an app: set the URL in your Partners dashboard under your app → Configuration → Webhooks (or subscribe via the Admin API).
3. For a single store: Shopify admin → Settings → Notifications → Webhooks → Create webhook.
4. Choose the topic (for example orders/create) and paste the Webhook Studio URL.
5. Trigger it — place a test order, or use the "Send test notification" button — and watch it land in the Inbox.

What a Shopify delivery looks like

A representative body, using Shopify’s field names. Your own deliveries appear in the Inbox exactly as sent, headers and raw bytes included.

{
  "id": 5123456789012,
  "admin_graphql_api_id": "gid://shopify/Order/5123456789012",
  "name": "#1001",
  "order_number": 1001,
  "created_at": "2026-07-21T09:14:02+08:00",
  "currency": "USD",
  "total_price": "48.00",
  "subtotal_price": "44.00",
  "total_tax": "4.00",
  "financial_status": "paid",
  "fulfillment_status": null,
  "test": true,
  "customer": {
    "id": 6234567890123,
    "email": "customer@example.com",
    "first_name": "Alex",
    "last_name": "Rivera"
  },
  "line_items": [
    {
      "id": 14234567890123,
      "title": "Field Notes — 3 pack",
      "quantity": 2,
      "price": "22.00",
      "sku": "FN-3PK",
      "product_id": 8234567890123,
      "variant_id": 44234567890123
    }
  ],
  "shipping_address": {
    "city": "Portland",
    "province": "Oregon",
    "country": "United States",
    "zip": "97205"
  }
}

Delivery headers

Event types

The events worth handling first. See Shopify’s own documentation for the complete list.

Verify the X-Shopify-Hmac-SHA256 header

Shopify signs each delivery with HMAC-SHA256 over the raw request body, keyed on your webhook secret. Verify before you parse, and before you act.

import express from 'express';
import crypto from 'crypto';

const app = express();

// express.raw() matters: the HMAC covers the exact bytes Shopify sent. A
// global express.json() upstream would reparse them and every check fails.
app.post('/webhooks/shopify', express.raw({ type: 'application/json' }), (req, res) => {
  const sent = req.get('X-Shopify-Hmac-SHA256') ?? '';
  const digest = crypto
    .createHmac('sha256', process.env.SHOPIFY_API_SECRET) // app client secret
    .update(req.body)                                     // Buffer, not a string
    .digest('base64');                                    // base64, NOT hex

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

  // Acknowledge inside 5 seconds or Shopify calls it a failure and retries.
  // Queue the work; never do it before responding.
  res.sendStatus(200);

  const topic = req.get('X-Shopify-Topic');       // 'orders/create'
  const deliveryId = req.get('X-Shopify-Webhook-Id'); // dedupe on this
  // enqueue({ topic, deliveryId, body: JSON.parse(req.body) })
});

Retries and delivery guarantees

Shopify allows a one-second connection timeout and five seconds for the whole request. Anything outside the 200 range — including 3xx redirects — is a failure. Failed deliveries are retried 8 times over roughly 4 hours, and if every attempt fails, a subscription created through the Admin API is deleted automatically and warning emails go to the store's emergency contacts. Losing the subscription entirely, not just the event, is what makes Shopify's timeout stricter in practice than most.

Common pitfalls

FAQ