snipcart-webhooks

Snipcart Webhooks

When to Use This Skill

• How do I receive Snipcart webhooks?
• How do I verify a Snipcart webhook is authentic? (there is no signature — read below)
• What is the X-Snipcart-RequestToken header and how do I validate it?
• Why does https://app.snipcart.com/api/requestvalidation/{token} return 404 or 401?
• How do I handle order.completed or v3/subscription.invoice.payment.succeeded?
• How do I implement the shippingrates.fetch / taxes.calculate webhooks?

Verification (core) — callback validation, NOT HMAC

Snipcart does not sign webhook payloads. There is no signature header, no HMAC, no shared webhook secret and no timestamp header. Every outbound request instead carries a random token in X-Snipcart-RequestToken, valid for one hour, which you prove genuine by calling Snipcart's API with your secret API key (HTTP Basic, key as the username, trailing colon, no password). 200 = genuine.

const PATTERN = /^[A-Za-z0-9_-]{1,128}$/;  // token is attacker-controlled: format-check
                                           // BEFORE it reaches the URL ('..' would
                                           // resolve to a different API endpoint)
async function validateRequestToken(token, secretKey) {
  if (!secretKey) throw new Error('SNIPCART_SECRET_API_KEY is not set'); // never fail open
  const t = (token || '').trim();
  if (!PATTERN.test(t)) return false;      // missing/malformed: reject, no API call
  const res = await fetch(`https://app.snipcart.com/api/requestvalidation/${t}`, {
    headers: {
      Authorization: `Basic ${Buffer.from(`${secretKey}:`).toString('base64')}`,
      Accept: 'application/json',
    },
    redirect: 'manual',                    // never forward the secret key to a redirect
    signal: AbortSignal.timeout(5000),
  }).catch(() => null);                    // network error/timeout -> fail closed
  return res?.status === 200;              // 404 = unknown/expired/already validated
}                                          // 401 = secret key missing/wrong (per Snipcart support)