Fanvue API Documentation

Every webhook Fanvue delivers carries an X-Fanvue-Signature header. By the end of this page your endpoint checks it on every request and rejects anything that fails, with a complete Express receiver you can copy. You need the signing secret for your destination and access to the raw request body in your framework. The secret depends on how you registered the endpoint, so start with Get your signing secret.

The signature header

X-Fanvue-Signature: t=<timestamp>,v0=<signature>

Field	Meaning
`t`	Unix timestamp in seconds, recording when Fanvue signed the request
`v0`	HMAC-SHA256 of `<t>.<raw body>`, hex encoded

During a signing-secret rotation the header carries two MACs: t=<timestamp>,v0=<old>,<new>. The second MAC arrives as a bare field with no =, continuing the v0 list. Compare against every MAC and accept when any one matches. If you read only the first, you reject every delivery signed with the newer secret for the length of the overlap. Deliveries also carry an X-Fanvue-Topic header. The signature covers <t>.<raw body> only, so that header is unauthenticated. Derive the topic from the signed body (type on the envelope, field presence on legacy events), never from the header.

Get your signing secret

Which secret signs your deliveries depends on how the webhook was registered. The two paths don’t share a secret.

How you registered the webhook	Secret that signs the delivery	Where you get it
Developer Area Events tab, or `webhooks.destinations` in the App Manifest	One per-app signing secret, shared by every endpoint on the app	View signing secret, any time
`POST /webhooks/subscriptions`	A per-subscription secret, unique to that subscription	The `signingSecret` field in the response, once

For the Events tab and the manifest, open your app’s Events tab in the Developer Area and click View signing secret. Keep the secret server-side in an environment variable such as FANVUE_WEBHOOK_SECRET, and never ship it in client-side code or commit it to source control. Security covers secret storage and rotation for the rest of your app. A subscription created with POST /webhooks/subscriptions gets its own secret, returned as signingSecret and shaped whsec_ followed by 64 hex characters:

{
  "id": "e0a5f3b2-6c41-4f0f-9d2a-1b7c8e3f4a90",
  "signingSecret": "whsec_3b1f8a0c2d4e6f8091a2b3c4d5e6f70819a2b3c4d5e6f70819a2b3c4d5e6f708"
}

Store signingSecret before you discard the create response. No endpoint reads it back. If you lose it, delete the subscription with DELETE /webhooks/subscriptions/{id} and create a new one, which mints a new secret.

How verification works

Parse the header

Split X-Fanvue-Signature on the comma. Read t and collect every v0 value, including bare fields that follow a v0= field. Reject the request when t is missing, repeated or not a plain decimal number, or when no MAC is present.

Reconstruct the signed payload

Concatenate t, a period and the raw request body: {timestamp}.{body}. Use the exact bytes Fanvue sent. Parsing the JSON and re-serialising it changes the bytes, and the signature won’t match.

Verify against the raw request body. Most frameworks expose the raw bytes through a hook, for example Express’s verify callback or express.raw(). Capture them before any JSON middleware mutates the request; otherwise every genuine delivery fails verification.

Compute the expected signature

Run HMAC-SHA256 over the signed payload with your signing secret and hex-encode the result.

Compare in constant time

Compare the expected signature against each MAC with a timing-safe comparison (crypto.timingSafeEqual in Node, hmac.compare_digest in Python). Accept when any MAC matches. A plain == leaks the secret through timing differences.

Reject stale timestamps

Reject the request when t is more than 300 seconds from the current time. The timestamp is inside the signed content, so a captured delivery cannot have its t refreshed.

Code samples

Both samples take the raw request body and the X-Fanvue-Signature header value and return whether the request is authentic.

Node.js
Python

import crypto from "node:crypto";

const SIGNING_SECRET = process.env.FANVUE_WEBHOOK_SECRET!;
const TOLERANCE_SECONDS = 300;

export function verifyWebhookSignature(
  rawBody: string,
  signatureHeader: string,
): boolean {
  // Parse "t=1234567890,v0=abc123" or "t=1234567890,v0=abc123,def456"
  let timestamp: string | undefined;
  const macs: string[] = [];
  let key: string | undefined;

  for (const field of signatureHeader.split(",")) {
    const separator = field.indexOf("=");
    if (separator !== -1) key = field.slice(0, separator).trim();
    const value = field.slice(separator + 1).trim();
    if (key === "t") timestamp = value;
    else if (key === "v0") macs.push(value);
  }

  if (!timestamp || !/^[0-9]+$/.test(timestamp) || macs.length === 0) {
    return false;
  }

  // Reject stale timestamps to block replays
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - Number(timestamp)) > TOLERANCE_SECONDS) {
    return false;
  }

  // Recompute the signature over `{timestamp}.{rawBody}`
  const expected = crypto
    .createHmac("sha256", SIGNING_SECRET)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");

  // Constant-time comparison against every MAC in the header
  return macs.some(
    (mac) =>
      mac.length === expected.length &&
      crypto.timingSafeEqual(Buffer.from(mac), Buffer.from(expected)),
  );
}

import hashlib
import hmac
import os
import time

SIGNING_SECRET = os.environ["FANVUE_WEBHOOK_SECRET"]
TOLERANCE_SECONDS = 300


def verify_webhook_signature(raw_body: bytes, signature_header: str) -> bool:
    # Parse "t=1234567890,v0=abc123" or "t=1234567890,v0=abc123,def456"
    timestamp = None
    macs = []
    key = None

    for field in signature_header.split(","):
        if "=" in field:
            key, _, value = field.partition("=")
            key = key.strip()
        else:
            value = field
        value = value.strip()
        if key == "t":
            timestamp = value
        elif key == "v0":
            macs.append(value)

    if not timestamp or not timestamp.isdigit() or not macs:
        return False

    # Reject stale timestamps to block replays
    if abs(int(time.time()) - int(timestamp)) > TOLERANCE_SECONDS:
        return False

    # Recompute the signature over `{timestamp}.{raw_body}`
    signed_payload = f"{timestamp}.".encode() + raw_body
    expected = hmac.new(
        SIGNING_SECRET.encode(),
        signed_payload,
        hashlib.sha256,
    ).hexdigest()

    # Constant-time comparison against every MAC in the header
    return any(hmac.compare_digest(expected, mac) for mac in macs)

Apps built on the Builder SDK call verifyWebhookHmac with fanvueSignatureContract(), and parseFanvueSignatureHeader implements the same parse rules. See SDK webhooks. When verification fails, respond 401 and don’t process the payload. When it succeeds, persist the event and return 2xx before you process it, as described in Delivery, retries and idempotency.

Complete receiver

This Express receiver answers the probe, verifies every other request against the raw body and accepts a second MAC during secret rotation. Answer 2xx to the unsigned verification probe before you check signatures, as it does, or POST /webhooks/subscriptions fails.

import crypto from "node:crypto";
import express from "express";

const app = express();
const SIGNING_SECRET = process.env.FANVUE_WEBHOOK_SECRET!;
const TOLERANCE_SECONDS = 300;

function verify(rawBody: string, header: string): boolean {
  let timestamp: string | undefined;
  const macs: string[] = [];
  let key: string | undefined;

  // Parse "t=<unix>,v0=<hex>" or "t=<unix>,v0=<hex>,<hex>" during rotation
  for (const field of header.split(",")) {
    const separator = field.indexOf("=");
    if (separator !== -1) key = field.slice(0, separator).trim();
    const value = field.slice(separator + 1).trim();
    if (key === "t") timestamp = value;
    else if (key === "v0") macs.push(value);
  }
  if (!timestamp || macs.length === 0) return false;

  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - Number(timestamp)) > TOLERANCE_SECONDS) return false;

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

  return macs.some(
    (mac) =>
      mac.length === expected.length &&
      crypto.timingSafeEqual(Buffer.from(mac), Buffer.from(expected)),
  );
}

app.post(
  "/webhooks/fanvue",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const rawBody = (req.body as Buffer).toString("utf8");
    const event = JSON.parse(rawBody);

    if (event.type === "fanvue.webhook.verification") {
      res.sendStatus(200);
      return;
    }

    const header = req.header("x-fanvue-signature");
    if (!header || !verify(rawBody, header)) {
      res.sendStatus(401);
      return;
    }

    // Persist event.id (or event.eventId on legacy events), then process asynchronously
    res.sendStatus(200);
  },
);

app.listen(3000);

Test the check

A test delivery carries a real signature, so a passing test proves the check end to end. Test a destination covers the Test action, the authorisation it needs and the API equivalent.

Receiving events

Creator events

Checkout link events

App events

Legacy events (deprecated)

Verify webhook signatures

The signature header

Get your signing secret

How verification works

Code samples

Complete receiver

Test the check

​The signature header

​Get your signing secret

​How verification works

​Code samples

​Complete receiver

​Test the check

The signature header

Get your signing secret

How verification works

Code samples

Complete receiver

Test the check