Connect your store to your own systems

Every webhook request carries three headers: webhook-id, webhook-timestamp and webhook-signature. The signature is an HMAC-SHA256 of the text id.timestamp.body made with your secret. The secret starts with whsec_, is shown once when it is created and is stored encrypted. The sample below verifies a request in Node.js.

import { createHmac, timingSafeEqual } from 'node:crypto';

// rawBody: the request body as raw text, before any JSON parsing
export function verifyWebhook(secret, headers, rawBody) {
  const id = headers['webhook-id'];
  const timestamp = headers['webhook-timestamp'];
  const signatures = headers['webhook-signature'];
  if (!id || !timestamp || !signatures) return false;

  // Time tolerance against replay attacks (5 minutes)
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  // The secret starts with "whsec_"; the rest is a base64-encoded key
  const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
  const expected = createHmac('sha256', key)
    .update(`${id}.${timestamp}.${rawBody}`)
    .digest();

  // The header can hold several space-separated "v1,<signature>" entries
  return signatures.split(' ').some((entry) => {
    const [version, signature] = entry.split(',');
    if (version !== 'v1' || !signature) return false;
    const given = Buffer.from(signature, 'base64');
    return given.length === expected.length && timingSafeEqual(given, expected);
  });
}

• Pass the body to the signature check as raw text, without parsing it as JSON first.
• webhook-id stays the same across every retry of the same event; store the ids you have processed and skip repeats.
• Any response outside 2xx counts as a failure and redirects are not followed; move heavy work to the background and answer quickly.
• After a secret rotation the header can carry two signatures; the sample tries all of them.