> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ofauth.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Realtime OnlyFans events

> Receive updates when messages, posts, and other OnlyFans activity change.

Realtime sends updates about OnlyFans activity for a connected [linked account](https://docs.ofauth.com/v3/api-reference/account/linked-accounts.md). First, ask the owner to approve account access through [authorization](https://docs.ofauth.com/v3/api-reference/link/authorize.md). Save that approval and the linked account under your app's user. Set up event delivery separately for each environment.

## Choose activity events

| Your feature | Events to consider |
| - | - |
| An inbox that receives new messages and reactions | `realtime.chat_message.received`, `realtime.chat_message.liked`, `realtime.chat_message.unliked` |
| Typing indicators and inbox counters | `realtime.chat_typing.updated`, `realtime.inbox_counts.updated` |
| Content updates | `realtime.post.published`, `realtime.stories.updated`, `realtime.post_fundraising.updated` |
| System notifications | `realtime.system_message.received`, `realtime.system_messages.updated`, `realtime.toasts.received` |

Use the [event catalog](https://docs.ofauth.com/v3/api-reference/realtime/onlyfans-events.md) to read the fields for each event. For example, a message event can trigger an inbox refresh. Before sending an automatic reply, check that you have not handled the event already. Also check that your app still has access to the account.

## Configure delivery

Choose how your app receives events:

| | Webhook | Server-Sent Events |
| - | - | - |
| How it works | OFAuth sends signed HTTPS requests to your receiver. | Your server, or a web page with a [stream URL](https://docs.ofauth.com/v3/guides/realtime-browser.md), keeps a long-lived HTTPS stream open. |
| Events | Account and access changes, plus enabled OnlyFans activity events. | OnlyFans activity events. |
| Time field | `occurredAt` | `receivedAt` |
| Missed events | Retried by OFAuth. | Replayed after `Last-Event-ID` for 15 minutes. |
| Your app must | Check signatures, save events, and return a success response. | Reconnect with the last event ID. |

![Activity reaches your server through signed HTTPS webhooks or a Server-Sent Events stream opened with an access token. Each option uses its own event format. Account access changes arrive only through webhooks.](https://mintcdn.com/ofauth/VVqOdSxbrh7mDF0M/images/v3/activity-delivery.svg?fit=max\&auto=format\&n=VVqOdSxbrh7mDF0M\&q=85\&s=7304eb5ef835fa211dd2bb46a26d255c)

Both options send activity. The stream does not send lifecycle events, such as account access changes. Read the event format for the option you choose. To show events in a web page, follow [Realtime from the browser](https://docs.ofauth.com/v3/guides/realtime-browser.md): never send an access token to a browser.

For webhook delivery, follow [Test webhooks locally](https://docs.ofauth.com/v3/guides/webhooks-local.md) for your first receiver. If you already have a receiver, [add a destination](https://docs.ofauth.com/v3/guides/webhook-setup.md#add-a-destination) in the authorization's environment and enable OnlyFans activity. Each destination has its own signing secret, which your receiver uses to check that events came from OFAuth. The account must be connected and shared with your application.

## Read the envelope

Each webhook event has outer fields, called its envelope. These fields include `eventId`, `type`, `schemaVersion`, `order`, `occurredAt`, `environment`, `integrationId`, `externalOauthClientId`, `authorizationId`, `linkedAccountId`, `test`, and `data`.

Use `authorizationId` to identify the authorization and `linkedAccountId` to select the affected account. `data` contains the fields documented for that event type. The fields depend on the event type. Check that event's fields in the [API reference](https://docs.ofauth.com/v3/api-reference.md) before reading message, user, or media details.

## Verify and acknowledge deliveries

Follow [Verify and handle webhooks](https://docs.ofauth.com/v3/guides/webhook-handler.md) to check the original body and timestamp. Use `eventId` to detect duplicates. Return a success response after you accept an event. Use `order` to avoid applying old linked-account updates over newer ones.

A delayed activity event does not prove the account is still connected. Read [linked accounts](https://docs.ofauth.com/v3/api-reference/account/linked-accounts.md) before acting when current status or permissions matter.

## Receive Realtime over Server-Sent Events

Request `https://api.ofauth.com/v3/realtime/events?linkedAccountId=` with the linked account ID, `Accept: text/event-stream`, and the access token in `Authorization: Bearer`:

```typescript theme={null}
async function listen(linkedAccountId: string, lastEventId?: string) {
  const response = await fetch(
    `https://api.ofauth.com/v3/realtime/events?linkedAccountId=${linkedAccountId}`,
    {
      headers: {
        accept: "text/event-stream",
        authorization: `Bearer ${process.env.OFAUTH_ACCESS_TOKEN}`,
        ...(lastEventId ? { "last-event-id": lastEventId } : {}),
      },
    },
  )
  if (!response.ok || !response.body) throw new Error(`Realtime ${response.status}`)
  let buffer = ""
  for await (const chunk of response.body.pipeThrough(new TextDecoderStream())) {
    buffer += chunk
    let end: number
    while ((end = buffer.indexOf("\n\n")) >= 0) {
      const frame = Object.fromEntries(
        buffer.slice(0, end).split("\n")
          .filter((line) => !line.startsWith(":"))
          .map((line) => [line.slice(0, line.indexOf(":")), line.slice(line.indexOf(":") + 2)]),
      )
      buffer = buffer.slice(end + 2)
      if (frame.id) lastEventId = frame.id
      if (frame.event === "closed") return { reason: JSON.parse(frame.data).reason, lastEventId }
      if (frame.event === "resync") await refetchState(linkedAccountId)
      else if (frame.event) handle(JSON.parse(frame.data))
    }
  }
  return { reason: "unavailable", lastEventId }
}
```

The stream starts with `retry: 3000` and an `id:` line with no event (its starting cursor; keep it as your last event ID). Each event has `id` (the event's `order`), `event` (its type), and `data` (the event JSON, shown below). A `: heartbeat` comment arrives every 15 seconds.

To resume after a disconnect, send the last `id` as `Last-Event-ID` (or the `lastEventId` query parameter). OFAuth replays missed events from the last 15 minutes, up to 1,000 events. If it can't, it sends one `event: resync`: fetch the current data from the API, then keep listening. Delivery is at least once, so skip an `eventId` you have handled.

Before the stream ends on purpose, it sends `event: closed` with `data: {"reason": …}`:

* `unavailable`: reconnect with `Last-Event-ID` after a short delay. Do the same when the stream ends without `closed`.
* `reauth`: the access token expired or was revoked, or the account is no longer shared with your app. Refresh the access token and reconnect once. Stop if that is refused (`401` or `403`).
* `replaced`: more than 10 streams were open for this linked account and authorization, and this was the oldest browser stream. Don't reconnect it.

Up to 10 streams can be open per linked account and authorization. Past that, the oldest browser stream (opened from a stream URL) ends with `replaced`. Server streams are never replaced: when all 10 are server streams, a new stream gets `429 stream_limit`; close one first.

Errors before the stream starts: `400` for a malformed request, `401` for missing or denied authentication, `406` for an `Accept` header that excludes both `text/event-stream` and `*/*`, `429 stream_limit` (10 server streams already open), and `503 realtime_unavailable` (retry later).

### The stream envelope

Stream events carry `eventId`, `type`, `schemaVersion`, `order`, `receivedAt`, `environment`, `integrationId`, `linkedAccountId`, `test`, and `data`. The stream envelope differs from the webhook envelope. Lifecycle events are webhook-only. When the account receives an inbox-count update, the stream can send:

```
id: 1
event: realtime.inbox_counts.updated
data: {"eventId":"evt_realtime_example123","type":"realtime.inbox_counts.updated","schemaVersion":"1","order":1,"receivedAt":"2026-04-23T14:30:15.143Z","environment":"live","integrationId":"int_example123","linkedAccountId":"conn_example123","test":false,"data":{"chatMessagesCount":1,"countPriorityChat":2,"unreadTips":3}}
```

These are the event's counter values, not increments to add for each delivery. In your application, map the connected authorization and linked account to their owner, keep environments separate, and save ordering state before applying updates.

## Test and troubleshoot

For webhooks, [verify the destination](https://docs.ofauth.com/v3/guides/webhook-setup.md), then trigger a matching action in Sandbox or Test. To receive the delivery locally, use a [Cloudflare Quick Tunnel](https://docs.ofauth.com/v3/guides/webhooks-local.md). For the stream, connect with a Test account and trigger an inbox-count change on that account. Confirm that the logged account and environment match your application records. An open stream alone does not prove that a matching activity event has occurred.

Keep sample test data out of production records. Events about account and access changes use `test: true` in Test, even for real accounts. Use `environment` to select the correct app records.

For missing events, verify the destination environment, Realtime setting, selected authorization, and account status. For invalid signatures, use the destination's current secret and the unmodified raw body. For duplicates, check that your app detects repeated `eventId` values. If your data is out of date, compare `order` values for the same account and fetch the current data.

Follow [Messaging](https://docs.ofauth.com/v3/guides/messaging.md) to build inbox workflows and [Webhooks](https://docs.ofauth.com/v3/api-reference/webhooks.md) for account and access events and delivery checks.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.