Set up OnlyFans webhooks
Get a signed HTTPS request when a fan messages, a sale lands, an account changes status or an action is decided.
Product page: OnlyFans webhooks
Webhooks tell your server when something happens, so you do not have to poll. BetterFans Link sends a signed POST with a JSON body to each endpoint that subscribes to the event's type.
Add an endpoint
- In the dashboard, open Webhooks and add an endpoint.
- Enter its URL. It must start with
https://. - Pick the event types it should get. You can change them later.
- Copy the signing secret. It starts with
whsec_.
Owners, admins and developers can add and change endpoints.
An endpoint belongs to the mode it was created in and gets only events of that mode. Create it with Test mode off for live accounts. Create it with Test mode on to test your handler: test mode sends the action.* events for actions made with a test key, and account.connected and link.failed for hosted links made with a test key. Account status, message, sale and subscriber events come only from linked accounts in live mode. See test mode events. Most teams keep one endpoint of each mode.
Event types
| Type | When it is sent |
|---|---|
account.connected | A creator account was linked to the workspace. |
account.status_changed | An account's status changed, for example to Needs relink. |
account.removed | An account was removed from the workspace. |
link.failed | A hosted link session ended without connecting. |
message.received | A fan sent a message. |
message.sent | The account sent a message to a fan. |
message.unsent | A message was unsent. |
message.liked | A message was liked. |
message.unliked | A like was taken off a message. |
message.purchased | A fan bought a paid message. |
transaction.created | A fan paid for something: a subscription, tip, message, post or stream. |
subscriber.new | A fan subscribed or resubscribed. |
fan.online | A subscribed fan came online. |
fan.typing | A fan is typing a message to the account. |
action.pending | An API client asked for a write that needs approval. |
action.executed | An approved write ran on the account. |
action.rejected | A person rejected a pending write. |
action.failed | An approved write failed on the platform. |
fanvue.payment.succeeded | Fanvue: a payment settled (subscription, tip, paid message, post or media). |
fanvue.reward.created | Fanvue: a referral reward was earned. |
fanvue.reward.reversed | Fanvue: a referral reward was taken back. |
fanvue.refund.created | Fanvue: a payment was refunded. |
fanvue.dispute.flagged | Fanvue: a payment was flagged for a dispute. |
fanvue.dispute.created | Fanvue: a fan disputed a payment. |
fanvue.subscription.activated | Fanvue: a fan subscribed, or subscribed again. |
fanvue.subscription.renewed | Fanvue: a subscription renewed. |
fanvue.subscription.deactivated | Fanvue: a subscription ended. |
fanvue.subscription.cancel_at_period_end_changed | Fanvue: a fan turned auto-renew off or back on. |
fanvue.message.received | Fanvue: a fan sent a message. |
fanvue.message.sent | Fanvue: the account sent a message to one fan. |
fanvue.message.mass_sent | Fanvue: the account sent a mass message. One notice per send, not per fan. |
fanvue.message.read | Fanvue: the account read a fan's messages. |
fanvue.message.read_by_fan | Fanvue: a fan read the account's messages. |
fanvue.message.deleted | Fanvue: a message was unsent. |
fanvue.message.reaction | Fanvue: someone reacted to a message. |
fanvue.chat.marked_unread | Fanvue: a chat was marked unread. |
fanvue.follow.created | Fanvue: someone followed the account. |
fanvue.post.liked | Fanvue: someone liked a post. |
fanvue.post.commented | Fanvue: someone commented on a post. |
fanvue.fan.status_changed | Fanvue: a fan's status with the account changed. |
fanvue.fan.presence_changed | Fanvue: a fan came online or went offline. |
Every event has the same envelope, with the type-specific fields in data. See events and payloads.
Which webhook events each platform sends
OnlyFans accounts send every shared event. Fansly accounts send all but message.liked, message.unliked, message.purchased and fan.online. Fanvue accounts send all but message.liked, message.unliked, fan.online and fan.typing, plus the fanvue.* events, Fanvue's own notifications passed on as Fanvue sends them. On a Fansly account, message.received, message.sent and message.unsent usually arrive within seconds of the message. transaction.created and subscriber.new come from the regular sync, so they usually arrive within 30 minutes and sometimes take over an hour.
Every event that names an account carries account.platform, or an action or link with its own platform. See platforms.
Receive an event
Your endpoint has to do four things.
- Read the raw body before any JSON parsing, and verify the signature against it.
- Drop events whose
webhook-idyou have already handled. The same event can arrive more than once. - Store the event and answer with any
2xxstatus within 15 seconds. - Do the slow work afterwards, from your own queue.
// Bun. See the verify page for Node, Python and Go.
import { verifyWebhook } from "./verify";
Bun.serve({
port: 3000,
async fetch(req) {
const body = await req.text();
if (!verifyWebhook(process.env.BFL_WEBHOOK_SECRET!, req.headers, body)) {
return new Response("bad signature", { status: 400 });
}
const event = JSON.parse(body);
if (await alreadyHandled(event.id)) return new Response("ok");
await enqueue(event);
return new Response("ok");
},
});alreadyHandled and enqueue stand for your own storage. The verifyWebhook function is on the verify page.
Send a test event
On an endpoint's page, send a test event of any type. It carries sample data with mode set to test, data.test set to true and accountId set to null. Use it to check your signature code and your handler before real events arrive. See test events.
The signing secret
- The secret is shown when you create the endpoint. After that, reveal it on the endpoint's page.
- Rotate it on the same page. The new secret signs every delivery from then on, and by default the old one keeps signing too for 24 hours, so your server passes its check while you switch. You can pick 72 hours, or end the old secret right away if it leaked. See Rotate the secret.
- Each endpoint has its own secret. Never reuse a secret across endpoints or put it in client code.
Deliveries
The endpoint's page lists every delivery with its status, attempts, response code and the first part of your response body. A delivery is pending, retrying, succeeded or failed. You can replay any delivery. See retries and replay.
An endpoint that fails every delivery for 5 days is turned off, with the reason shown on its page. Fix it, then turn it back on.
Events without an endpoint
The Events page lists every event in your workspace, whether or not an endpoint subscribed to it. Use it to see what would have been sent, or to catch up after an outage.
The three exceptions are message.sent, fan.online and fan.typing. A mass message is one sent message for every fan who gets it, and fans come online and type far more often than anything else here happens, so each is recorded only while an enabled live endpoint of yours lists it. The fanvue.* events are recorded the same way: only while an enabled live endpoint lists the type.