Webhooks Overview

• Message Received → creator.message.received
• Message Sent → creator.message.sent
• Message Read → creator.message.read
• New Follower → creator.follow.created
• New Subscriber → creator.subscription.activated
• Subscription Cancelled → creator.subscription.cancel_at_period_end_changed
• Subscription Expired → creator.subscription.deactivated
• Purchase Received → creator.payment.succeeded
• Tip Received → creator.payment.succeeded

​

Setting up a webhook

1. Set up an endpoint on your backend to receive webhooks. It should accept POST requests from our API and return a 2xx response.
2. Navigate to the Fanvue Developer Area, select your app and open the Events tab.
3. Click Add Webhook. In the dialog, enter your Endpoint URL and select the events you want this endpoint to receive. Use Select All to subscribe to every event, or tick individual events. A single endpoint can listen for multiple events.
4. Click Save. The webhook is created and appears in the Events & Endpoints list, where you can enable or disable it with the toggle.

​

Missing scope warnings

​

Managing and testing webhooks

• Edit, change the endpoint URL or the events it subscribes to.
• Test, send a sample payload to your endpoint so you can confirm it is reachable and that your signature verification works, without waiting for a real user action.
• History, review recent delivery attempts for the webhook.
• Delete, remove the webhook.

​

How deliveries work

• Each webhook is delivered as an HTTP POST with Content-Type: application/json.
• The request body contains an event-specific JSON payload.
• Your endpoint should return a 2xx response as soon as you successfully receive and persist the event.
• Delivery is at least once: a failed attempt is retried up to 5 times, so expect duplicates. Each payload carries an eventId for deduplication.

​

Verifying webhook signatures

​

Testing locally

• Expose your local server with a tunneling tool (for example, ngrok) and copy the public HTTPS URL.
• Add a webhook in the Events tab with that URL and the events you want to receive.
• Use the Test action in the webhook’s … menu to send a sample payload to your endpoint, or trigger the event in a test environment, then inspect the request reaching your server.

​

Troubleshooting: test events work, but production events do not

​

1) Confirm required OAuth scopes are enabled for each event

​

2) Confirm the webhook event checkbox is enabled

​

3) Re-authorize the app after scope changes

1. Open https://fanvue.com/settings/account/third-party-apps
2. Revoke access for your app
3. Reconnect the app and approve the requested scopes again

​

4) Validate with a real production action

​

Example endpoint (Node.js / Express)

import crypto from "crypto";
import express from "express";

const app = express();

const SIGNING_SECRET = process.env.FANVUE_WEBHOOK_SECRET!;
const TOLERANCE_SECONDS = 300; // 5 minutes

function verifyWebhookSignature(
  payload: string,
  signatureHeader: string,
): boolean {
  const parts = signatureHeader.split(",");
  let timestamp: string | undefined;
  let signature: string | undefined;

  for (const part of parts) {
    const [key, value] = part.split("=");
    if (key === "t") timestamp = value;
    if (key === "v0") signature = value;
  }

  if (!timestamp || !signature) return false;

  const currentTime = Math.floor(Date.now() / 1000);
  if (Math.abs(currentTime - parseInt(timestamp, 10)) > TOLERANCE_SECONDS) {
    return false;
  }

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

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature),
  );
}

// Use raw body for signature verification
app.use(
  express.json({
    verify: (req: any, _res, buf) => {
      req.rawBody = buf.toString();
    },
  }),
);

app.post("/webhooks/fanvue", (req: any, res) => {
  const signatureHeader = req.headers["x-fanvue-signature"];

  if (
    !signatureHeader ||
    !verifyWebhookSignature(req.rawBody, signatureHeader)
  ) {
    res.status(401).json({ error: "Invalid signature" });
    return;
  }

  const event = req.body;
  // Process the event...

  res.sendStatus(200);
});

app.listen(3000);