Webhooks Overview

Webhooks are a way for your app to receive live notifications of activity on your user’s accounts.

Currently we support 5 different event types:

• Message Received
• New Follower
• New Subscriber
• Purchase Received
• Tip Received

Here’s how to use them:

1. Setup an endpoint on your backend to receive webhooks, this should be able to receive POST requests from our API
2. Navigate to the Fanvue Developer Area, select your app and go to the Webhooks tab
3. Enter the desired URL
4. Press Save and then enable the webhook by checking the box next to it

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.

Verifying webhook signatures

Every webhook request includes an X-Fanvue-Signature header. You should verify this signature on every request to ensure it came from Fanvue and was not tampered with.

Signature format

The header value has the format:

t=<timestamp>,v0=<signature>

• t is a Unix timestamp (seconds since epoch) indicating when the request was signed.
• v0 is the HMAC-SHA256 signature encoded as a hexadecimal string.

Finding your signing secret

Your webhook signing secret is available in the Fanvue Developer Area:

1. Navigate to your app’s Webhooks tab
2. Click “View Signing Secret”

Keep this secret secure and never expose it in client-side code.

Verification steps

1. Extract the timestamp (t) and signature (v0) from the header
2. Construct the signed payload by concatenating the timestamp, a period, and the raw request body: {timestamp}.{body}
3. Compute the expected signature using HMAC-SHA256 with your signing secret
4. Compare the expected signature with the received signature using a timing-safe comparison
5. Optionally, check that the timestamp is within an acceptable window (e.g., 5 minutes) to prevent replay attacks

Verification example (Node.js)

1
import crypto from "crypto";
2
3
const SIGNING_SECRET = process.env.FANVUE_WEBHOOK_SECRET!;
4
const TOLERANCE_SECONDS = 300; // 5 minutes
5
6
export function verifyWebhookSignature(
7
  payload: string,
8
  signatureHeader: string
9
): boolean {
10
  // Parse header: "t=1234567890,v0=abc123..."
11
  const parts = signatureHeader.split(",");
12
  let timestamp: string | undefined;
13
  let signature: string | undefined;
14
15
  for (const part of parts) {
16
    const [key, value] = part.split("=");
17
    if (key === "t") timestamp = value;
18
    if (key === "v0") signature = value;
19
  }
20
21
  if (!timestamp || !signature) {
22
    return false;
23
  }
24
25
  // Check timestamp tolerance (optional but recommended)
26
  const currentTime = Math.floor(Date.now() / 1000);
27
  if (Math.abs(currentTime - parseInt(timestamp, 10)) > TOLERANCE_SECONDS) {
28
    return false;
29
  }
30
31
  // Compute expected signature
32
  const signedPayload = `${timestamp}.${payload}`;
33
  const expectedSignature = crypto
34
    .createHmac("sha256", SIGNING_SECRET)
35
    .update(signedPayload)
36
    .digest("hex");
37
38
  // Timing-safe comparison
39
  return crypto.timingSafeEqual(
40
    Buffer.from(signature),
41
    Buffer.from(expectedSignature)
42
  );
43
}

Testing locally

• Expose your local server with a tunneling tool (for example, ngrok) and copy the public HTTPS URL.
• Set that URL in the Webhooks UI for the event type you want to receive.
• Trigger the event in a test environment and inspect the request reaching your server.

Troubleshooting: test events work, but production events do not

If webhook test deliveries succeed but real user activity does not trigger events, use this checklist.

1) Confirm required OAuth scopes are enabled for each event

2) Confirm the webhook event checkbox is enabled

In your app’s Webhooks tab, verify the event type is selected for the webhook endpoint you configured.

3) Re-authorize the app after scope changes

If scopes were added after users already connected your app, previously granted consent may not include those scopes yet.

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

Use an actual follow, purchase, subscription, tip, or message event from a separate account and verify delivery on your endpoint logs.

Example endpoint (Node.js / Express)

1
import crypto from "crypto";
2
import express from "express";
3
4
const app = express();
5
6
const SIGNING_SECRET = process.env.FANVUE_WEBHOOK_SECRET!;
7
const TOLERANCE_SECONDS = 300; // 5 minutes
8
9
function verifyWebhookSignature(payload: string, signatureHeader: string): boolean {
10
  const parts = signatureHeader.split(",");
11
  let timestamp: string | undefined;
12
  let signature: string | undefined;
13
14
  for (const part of parts) {
15
    const [key, value] = part.split("=");
16
    if (key === "t") timestamp = value;
17
    if (key === "v0") signature = value;
18
  }
19
20
  if (!timestamp || !signature) return false;
21
22
  const currentTime = Math.floor(Date.now() / 1000);
23
  if (Math.abs(currentTime - parseInt(timestamp, 10)) > TOLERANCE_SECONDS) {
24
    return false;
25
  }
26
27
  const signedPayload = `${timestamp}.${payload}`;
28
  const expectedSignature = crypto
29
    .createHmac("sha256", SIGNING_SECRET)
30
    .update(signedPayload)
31
    .digest("hex");
32
33
  return crypto.timingSafeEqual(
34
    Buffer.from(signature),
35
    Buffer.from(expectedSignature)
36
  );
37
}
38
39
// Use raw body for signature verification
40
app.use(
41
  express.json({
42
    verify: (req: any, _res, buf) => {
43
      req.rawBody = buf.toString();
44
    },
45
  })
46
);
47
48
app.post("/webhooks/fanvue", (req: any, res) => {
49
  const signatureHeader = req.headers["x-fanvue-signature"];
50
51
  if (!signatureHeader || !verifyWebhookSignature(req.rawBody, signatureHeader)) {
52
    res.status(401).json({ error: "Invalid signature" });
53
    return;
54
  }
55
56
  const event = req.body;
57
  // Process the event...
58
59
  res.sendStatus(200);
60
});
61
62
app.listen(3000);