fanvue-webhooks

Fanvue Webhooks

When to Use This Skill

• Setting up a Fanvue webhook endpoint for a Developer Area app
• Verifying the X-Fanvue-Signature header (or debugging why it fails)
• Why does POST /webhooks/subscriptions fail against my endpoint? (the unsigned probe)
• Handling creator, checkout link, payout or app billing events
• Migrating from legacy flat events (purchase.new, tip.new, subscription.new) to creator.*

Verification (core)

Every delivery carries:

X-Fanvue-Signature: t=<unix seconds>,v0=<hex>
X-Fanvue-Signature: t=<unix seconds>,v0=<old hex>,<new hex>   # during secret rotation

The signature is HMAC-SHA256 over <t>.<raw body>, hex encoded, keyed with the signing secret exactly as Fanvue gives it (don't strip whsec_). The rotation MAC arrives as a bare field with no =, so parse the header statefully and accept when any MAC matches. Reject t more than 300 seconds from now, and respond 401 on failure.

Node (from examples/express/):

function parseSignatureHeader(header) {
  let key;
  let timestamp;
  let timestampCount = 0;
  const macs = [];

  for (const field of header.split(',')) {
    const separator = field.indexOf('=');
    if (separator !== -1) key = field.slice(0, separator).trim();
    // With separator === -1 this is the whole bare field.
    const value = field.slice(separator + 1).trim();
    if (key === 't') {
      timestamp = value;
      timestampCount += 1;
    } else if (key === 'v0' && value) {
      macs.push(value.toLowerCase());
    }
  }

  return { timestamp, timestampCount, macs };
}

function verifyFanvueSignature(
  rawBody,
  header,
  secret,
  toleranceSeconds = TOLERANCE_SECONDS,
  nowSeconds = Math.floor(Date.now() / 1000)
) {
  if (!header) {
    return { valid: false, error: 'Missing X-Fanvue-Signature header' };
  }

  const { timestamp, timestampCount, macs } = parseSignatureHeader(header);
  if (timestampCount !== 1 || !/^[0-9]+$/.test(timestamp) || macs.length === 0) {
    return { valid: false, error: 'Malformed X-Fanvue-Signature header' };
  }

  // `t` is inside the signed content, so it can't be refreshed on a replay.
  if (Math.abs(nowSeconds - Number(timestamp)) > toleranceSeconds) {
    return { valid: false, error: 'Timestamp outside tolerance' };
  }

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.`)
    .update(rawBody)
    .digest('hex');

  // Accept when ANY MAC matches (two MACs are sent during secret rotation).
  const matched = macs.some(
    (mac) =>
      mac.length === expected.length &&
      crypto.timingSafeEqual(Buffer.from(mac), Buffer.from(expected))
  );

  return matched ? { valid: true } : { valid: false, error: 'Invalid signature' };
}