> ## 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.

# Webhook delivery reference

> Webhook fields, signature checks, event order, retries, and test deliveries.

OFAuth sends webhook requests to the URLs you add as destinations. These requests report account access changes and the OnlyFans activity events you enable. Follow [Set up webhooks](https://docs.ofauth.com/v3/guides/webhook-setup.md) to configure a destination and [Verify and handle webhooks](https://docs.ofauth.com/v3/guides/webhook-handler.md) to receive deliveries.

## Envelope

Normal events use the JSON format below, called an envelope. The fields inside `data` depend on `type`. The [destination verification challenge](#destination-verification) is a separate message.

```json theme={null}
{
  "eventId": "...",
  "type": "linked_account.expired",
  "schemaVersion": "1",
  "order": 42,
  "occurredAt": "2026-10-12T14:30:15.143Z",
  "environment": "live",
  "integrationId": "int_example123",
  "externalOauthClientId": "external_oauth_client_example123",
  "authorizationId": "external_live_example123",
  "linkedAccountId": "conn_example123",
  "test": false,
  "data": {
    "authorization_id": "external_live_example123",
    "linked_account_id": "conn_example123",
    "reason": "provider_session_expired"
  }
}
```

| Field | Description |
| - | - |
| `eventId` | Unique for each event. Use it to detect duplicates. |
| `type` | Event type. See the [event catalogs](#event-catalogs). |
| `schemaVersion` | `"1"`. |
| `order` | Ordering value. For the same linked account, a higher `order` is newer. |
| `occurredAt` | When the event happened. |
| `environment` | `sandbox`, `test`, or `live`. |
| `integrationId` | Your External Integration. |
| `externalOauthClientId` | The environment client the authorization belongs to. |
| `authorizationId` | The authorization. Map it to your user. |
| `linkedAccountId` | The linked account the event is about. `null` for `authorization.*` events. |
| `test` | Marks test deliveries. Lifecycle events also set this to `true` in Sandbox and Test, including Test events about real accounts. |
| `data` | The details of this event. |

## Event catalogs

[Lifecycle events](https://docs.ofauth.com/v3/api-reference/system-webhook-events.md) report changes to accounts and access. An authorization records the accounts and permissions that an owner approved. [OnlyFans activity events](https://docs.ofauth.com/v3/api-reference/realtime/onlyfans-events.md) describe messages, posts, stories, and other supported activity. Each catalog lists event types and their fields.

## Destination verification

Before normal event delivery, OFAuth sends a signed JSON body with `type: "ofauth.webhook.challenge"` and a `challenge` string. This verification message does not use the normal event envelope. Verify its signature and return the exact challenge string as a `text/plain` response body with a `2xx` status. Do not add JSON quotes or a newline. See the [receiver example](https://docs.ofauth.com/v3/guides/webhook-handler.md#verify-destination-ownership).

## Signatures

Deliveries use Standard Webhooks with `webhook-id`, `webhook-timestamp`, and `webhook-signature` headers. Verify the unmodified request body with the destination's signing secret before using any field. A [Standard Webhooks verifier](https://docs.ofauth.com/v3/guides/webhook-handler.md) checks the signature and timestamp.

## Acknowledgements and retries

Save events before returning a `2xx` success response if they change data in your app. Return the response promptly, then process the saved event. OFAuth retries failed deliveries with a wait between attempts.

## Idempotency and ordering

Use `eventId` as the key for saved events. Receiving the same `eventId` again must not repeat a customer update. For one linked account, a higher `order` represents a newer event. Deliveries can arrive out of order after retries. Do not compare ordering values across accounts.

Lifecycle events tell you that access or account details changed. Read [linked accounts](https://docs.ofauth.com/v3/api-reference/account/linked-accounts.md) when you need current names, scopes, or status. For events about an authorization, fetch its current accounts and permissions. The order in which events arrive may differ from the order in which changes happened.

## Test deliveries

> [!NOTE]
>
> To receive deliveries on your computer, expose your local receiver with a [Cloudflare Quick Tunnel](https://docs.ofauth.com/v3/guides/webhooks-local.md).

The receiver example's optional checks use sample test data with `test: true` and made-up IDs. Keep that data out of customer records.

The flag alone does not mean that the IDs are made up. Events about account and access changes in Sandbox and Test also have `test: true`. Test events can describe real accounts you chose for testing. Use `environment` to keep Sandbox, Test, and Live state separate, and process each environment's account events against its own records.

Lifecycle events are delivered through webhooks. OnlyFans activity can also arrive over a [Server-Sent Events stream](https://docs.ofauth.com/v3/guides/realtime-onlyfans-events.md#receive-realtime-over-server-sent-events), whose envelope uses `receivedAt` and differs from the webhook envelope.


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