Webhook handler in a Cloudflare Worker

Verify, idempotency-check, and act on Shoppex webhooks from a Worker.

Cloudflare Workers are a good fit for webhook handlers — cheap, fast, globally distributed, no servers to babysit. This tutorial wires up a worker that receives Shoppex webhook deliveries, verifies the signature, deduplicates by delivery ID, and reacts to the event.

What you will have at the end

• A deployed Cloudflare Worker that listens for Shoppex events.
• HMAC-SHA256 signature verification against the V2 header.
• Idempotency using Cloudflare KV (so you can safely receive duplicates).
• A registered Shoppex webhook pointing at the worker.

Prerequisites

• A Cloudflare account with Workers enabled.
• wrangler CLI installed (npm i -g wrangler or bun add -g wrangler).
• A Shoppex shop with an API key that has webhooks.write.

Step 1 — Create the worker

npx wrangler init shoppex-webhook-worker
cd shoppex-webhook-worker

Pick the “Hello World” Worker template, TypeScript. You will have a src/index.ts to edit.

Step 2 — Add a KV namespace for idempotency

Shoppex assigns a unique delivery_id to each delivery. Manually retrying a webhook can create duplicates, so record the IDs you have already processed. If you see the same ID twice, short-circuit and skip reprocessing.

npx wrangler kv:namespace create WEBHOOK_DELIVERIES

Wrangler prints a binding snippet — copy it into wrangler.toml:

[[kv_namespaces]]
binding = "WEBHOOK_DELIVERIES"
id = "your-namespace-id-from-wrangler"

Step 3 — Add the webhook secret

The webhook secret is what you will use to verify HMAC signatures. Add it as a wrangler secret (not in code, not in wrangler.toml):

npx wrangler secret put SHOPPEX_WEBHOOK_SECRET
# Paste the secret when prompted

You will get the secret from Shoppex in step 8 (when you create the webhook), so come back here once.

Step 4 — Write the handler

Replace src/index.ts:

export interface Env {
  WEBHOOK_DELIVERIES: KVNamespace;
  SHOPPEX_WEBHOOK_SECRET: string;
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    if (request.method !== 'POST') {
      return new Response('Method not allowed', { status: 405 });
    }

    // 1. Read raw body — required for signature verification
    const rawBody = await request.text();

    // 2. Extract Shoppex headers
    const signatureV2 = request.headers.get('X-Shoppex-Signature-V2');
    const deliveryId = request.headers.get('X-Shoppex-Delivery');
    const timestamp = request.headers.get('X-Shoppex-Timestamp');
    const event = request.headers.get('X-Shoppex-Event');

    if (!signatureV2 || !deliveryId || !timestamp || !event) {
      return new Response('Missing required Shoppex headers', { status: 400 });
    }

    // 3. Reject deliveries older than 5 minutes (replay protection)
    const now = Math.floor(Date.now() / 1000);
    const ts = parseInt(timestamp, 10);
    if (Math.abs(now - ts) > 300) {
      return new Response('Timestamp out of window', { status: 400 });
    }

    // 4. Verify HMAC-SHA256 signature
    const isValid = await verifySignature(
      signatureV2,
      deliveryId,
      timestamp,
      rawBody,
      env.SHOPPEX_WEBHOOK_SECRET,
    );
    if (!isValid) {
      return new Response('Invalid signature', { status: 401 });
    }

    // 5. Idempotency — check if this delivery has already been seen
    const seen = await env.WEBHOOK_DELIVERIES.get(deliveryId);
    if (seen) {
      return new Response('Already processed', { status: 200 });
    }

    // 6. Parse and act on the event
    const payload = JSON.parse(rawBody);
    await handleEvent(event, payload, env);

    // 7. Record the delivery ID with a 7-day TTL
    await env.WEBHOOK_DELIVERIES.put(deliveryId, '1', { expirationTtl: 60 * 60 * 24 * 7 });

    return new Response('ok', { status: 200 });
  },
};

async function verifySignature(
  signatureHeader: string,
  deliveryId: string,
  timestamp: string,
  rawBody: string,
  secret: string,
): Promise<boolean> {
  // Header format: "v1,t={timestamp},h={hex_signature}"
  const segments = signatureHeader.split(',').map((part) => part.trim());
  const parts = segments.reduce<Record<string, string>>((acc, part) => {
    const [k, v] = part.split('=');
    if (k && v) acc[k] = v;
    return acc;
  }, {});
  const signature = parts.h;
  if (!segments.includes('v1') || parts.t !== timestamp || !/^[0-9a-f]{64}$/i.test(signature ?? '')) return false;

  // Message format: "{deliveryId}.{timestamp}.{rawBody}"
  const message = `${deliveryId}.${timestamp}.${rawBody}`;

  // Compute HMAC-SHA256 with Web Crypto API
  const enc = new TextEncoder();
  const key = await crypto.subtle.importKey(
    'raw',
    enc.encode(secret),
    { name: 'HMAC', hash: 'SHA-256' },
    false,
    ['sign'],
  );
  const sigBuffer = await crypto.subtle.sign('HMAC', key, enc.encode(message));
  const expected = Array.from(new Uint8Array(sigBuffer))
    .map((b) => b.toString(16).padStart(2, '0'))
    .join('');

  // Constant-time compare
  if (expected.length !== signature.length) return false;
  let mismatch = 0;
  for (let i = 0; i < expected.length; i++) {
    mismatch |= expected.charCodeAt(i) ^ signature.charCodeAt(i);
  }
  return mismatch === 0;
}

async function handleEvent(event: string, payload: any, env: Env): Promise<void> {
  switch (event) {
    case 'order:paid':
      console.log('Order paid:', payload.data.uniqid, payload.data.total);
      // Your business logic here — send a Slack message, fulfill in your system, and more.
      break;
    case 'order:disputed':
      console.warn('Dispute opened on order:', payload.data.uniqid);
      break;
    case 'subscription:renewed':
      console.log('Subscription renewed:', payload.data.uniqid);
      break;
    default:
      console.log('Unhandled event:', event);
  }
}

Step 5 — Test locally

npx wrangler dev

Wrangler runs the worker at http://localhost:8787. Send a POST request with fake headers to confirm it returns 400 for missing headers. Then send full headers with a wrong signature to confirm it returns 401. That is the right behavior.

Step 6 — Deploy

npx wrangler deploy

Wrangler gives you a URL like https://shoppex-webhook-worker.your-account.workers.dev. Copy it.

Step 7 — Register the webhook in Shoppex

From your dashboard at Settings → Developer → Webhooks or through the API:

curl https://api.shoppex.io/dev/v1/webhooks \
  -H "Authorization: Bearer shx_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://shoppex-webhook-worker.your-account.workers.dev",
    "events": ["order:paid", "order:disputed", "subscription:renewed"]
  }'

The response includes a secret. Save it immediately. Shoppex shows it only once.

Step 8 — Set the secret in the worker

npx wrangler secret put SHOPPEX_WEBHOOK_SECRET
# Paste the secret you got in step 7

Step 9 — Verify

Trigger a real event. Make a purchase on your shop, or use the dashboard’s “send test event” button on the webhook configuration page. Check your worker logs:

npx wrangler tail

You will see the event come in, get verified, and be processed.

Event reference

Common events you will likely subscribe to:

• order:created — new order, not yet paid.
• order:paid — payment confirmed. This is the event 90% of integrations care about.
• order:cancelled, order:disputed — bad-path events worth knowing about.
• subscription:renewed, subscription:cancelled — recurring billing lifecycle.
• subscription:trial:started, :trial:ended — for nudge flows.
• product:stock — direct catalog stock update. For stock consumed by checkout, use order:paid or order:paid:product.

Up to 12 events per webhook, and 15 webhooks per shop in total.

Retry behavior — important

If your worker returns a non-2xx status or times out (30s limit), Shoppex retries automatically. It uses an exponential backoff of 2 min, 4 min, 8 min, 16 min between tries. After 5 total attempts (the first call plus 4 retries) the delivery is marked failed.

You can manually re-queue any failed delivery from the dashboard or through POST /dev/v1/webhooks/logs/:id/retry. The same delivery_id is reused. That is why idempotency (the KV check above) matters.

Practical implications:

• Your worker must be reliable. Use a Worker (which is globally distributed) rather than a single-region origin server. Transient failures are forgiven automatically. Sustained outages still get the delivery through if you recover within the ~30-minute retry window.
• Make handlers idempotent. Both automatic retries and your own manual retries will re-send the same delivery_id. The KV check above is what catches both cases.
• Watch for failures. If a delivery uses all 5 attempts, it is done. Shoppex will not try again. Monitor your worker logs (Cloudflare Analytics or wrangler tail) and the Shoppex webhook-logs dashboard for failed entries. Once you have fixed the root cause, manually re-queue those entries.

Common pitfalls

• Parsing the body before verifying. You must use request.text() to get the exact raw bytes Shoppex signed. If you request.json() first and re-serialize, the message no longer matches the signature.
• Reading headers case-sensitively. The Fetch API in Workers gives you case-insensitive access, but be consistent.
• Forgetting the timestamp window. Without a 5-minute timestamp check, an attacker who captured one signed payload can replay it forever.
• Not enabling KV in production. Without idempotency, a manual retry double-processes the order. Worth the 5 minutes of KV setup.

Reference: Webhooks

Full event list, payload shapes, and the signature spec.