statsig-webhooks

Statsig Webhooks

When to Use This Skill

• Setting up a Statsig Event Webhook (the "Generic Webhook" integration)
• Debugging X-Statsig-Signature verification failures
• Processing exposure events or config-change notifications (feature gate, experiment, or dynamic config created / updated events)
• Handling Statsig's JSON batch payloads (arrays) and the config-change { "data": [...] } envelope
• Answering the url_verification handshake so the webhook actually registers (a missed handshake fails silently — no events, no log entries)

Essential Code (USE THIS)

Statsig signs every webhook request with HMAC-SHA256 using a Slack/Stripe-style scheme (this is not the Standard Webhooks spec). The signed content is the literal string v0:{timestamp}:{raw_body}, and the result is sent as X-Statsig-Signature: v0=<hex>. Use the raw request body — parsing JSON before verifying will change byte ordering and break the signature.

Note: Statsig's X-Statsig-Request-Timestamp is a Unix timestamp in milliseconds (13 digits), not seconds.

URL Validation Handshake (answer this or the webhook never registers)

When you save the Generic Webhook integration, Statsig POSTs a validation request to the destination URL and registers the webhook only if the endpoint echoes the code back:

{ "data": { "event": "url_verification", "verification_code": "abc123" } }

Respond 200 with a JSON body carrying the same value:

{ "verification_code": "abc123" }

A missed handshake fails silently: the webhook never registers, no event is ever delivered, and nothing appears in any delivery log. Answer it before enforcing signature verification — it only echoes a value the caller supplied, the same way an unauthenticated URL-check ping is answered for providers like Mailchimp. The Express handler below includes the responder.

Statsig Signature Verification (JavaScript)

const crypto = require('crypto');

function verifyStatsigRequest(rawBody, signatureHeader, timestampHeader, signingSecret) {
  if (!signatureHeader || !timestampHeader || !signingSecret) return false;

  // Statsig's timestamp is a Unix time in MILLISECONDS (13 digits)
  const timestamp = parseInt(timestampHeader, 10);
  if (Number.isNaN(timestamp)) return false;

  // Replay protection (best practice; Statsig does not document a tolerance):
  // reject requests whose timestamp is more than 5 minutes from now.
  if (Math.abs(Date.now() - timestamp) > 5 * 60 * 1000) return false;

  // Statsig signs the literal string: "v0:" + timestamp + ":" + raw body
  const basestring = `v0:${timestampHeader}:${rawBody}`;
  const expected = 'v0=' + crypto
    .createHmac('sha256', signingSecret)
    .update(basestring, 'utf8')
    .digest('hex');

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