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

# Verify and handle webhooks

> Check that webhooks came from OFAuth and handle them safely.

Use this example to build a receiver: the route in your app that accepts webhook requests. The receiver checks signatures and returns a response to OFAuth. It prints the event ID and type without changing application state. To receive deliveries on your computer, follow [Test webhooks locally](https://docs.ofauth.com/v3/guides/webhooks-local.md).

## Before you start

Use Node.js 22 or later and your destination's signing secret.

## Run the receiver

![Check the signature of the original request and reject invalid deliveries. Return verified challenge text. Save normal events, check eventId for duplicates, return success, then process each saved event.](https://mintcdn.com/ofauth/VVqOdSxbrh7mDF0M/images/v3/webhook-handling.svg?fit=max\&auto=format\&n=VVqOdSxbrh7mDF0M\&q=85\&s=560405e2853ba8f22bf67d8646a842fa)

Clone the [webhook example on GitHub](https://github.com/ofauth-source/example-node-webhooks) and install its dependencies. It uses the `standardwebhooks` package to verify signatures. Its [receiver.js](https://github.com/ofauth-source/example-node-webhooks/blob/main/receiver.js) registers the raw-body handler before JSON parsing and verifies each signature before reading event fields.

```bash theme={null}
git clone https://github.com/ofauth-source/example-node-webhooks.git
cd example-node-webhooks
npm install
```

Set `OFAUTH_WEBHOOK_SECRET` in `.env` to the destination's signing secret, then start the receiver. Keep `.env` out of version control.

```bash theme={null}
npm start
```

The process listens on port `3001` without printing a startup message. A valid event returns `204` and prints its ID and type. An invalid or stale signature returns `400`. To make this receiver reachable from OFAuth, follow [Test webhooks locally](https://docs.ofauth.com/v3/guides/webhooks-local.md). If you already run a public HTTPS receiver, continue at [Add a destination](https://docs.ofauth.com/v3/guides/webhook-setup.md#add-a-destination).

## Verify destination ownership

During destination verification, OFAuth sends a signed event with `type: "ofauth.webhook.challenge"` and a `challenge` string. Verify its signature, then return that exact string as the `text/plain` response body with a `2xx` status. Do not JSON-encode it or add a newline. The [example receiver](https://github.com/ofauth-source/example-node-webhooks/blob/main/receiver.js) handles this before checking normal event fields.

## Apply events to your application

Before accepting events that update your app, save them to a database or a queue that keeps data after a restart. Use `eventId` to detect duplicates so retries do not repeat an action. Keep sample test data out of customer records, and keep each environment's state separate. Events about account and access changes have `test: true` in Test, even when they describe real accounts. See [Test deliveries](https://docs.ofauth.com/v3/api-reference/webhooks.md#test-deliveries).

For linked-account events, use `order` to avoid applying older updates over newer ones. When an authorization changes, read its current [linked-account list](https://docs.ofauth.com/v3/api-reference/account/linked-accounts.md). Follow the [account and access event list](https://docs.ofauth.com/v3/api-reference/system-webhook-events.md) and [activity catalog](https://docs.ofauth.com/v3/api-reference/realtime/onlyfans-events.md) to select the event types your feature uses. After checking the signature, return success for event types you do not use.

Return a `2xx` success response as soon as you save the event. Do longer work afterwards. OFAuth retries failed deliveries with a wait between attempts. See the [delivery reference](https://docs.ofauth.com/v3/api-reference/webhooks.md).

The sample verifies and logs deliveries. Before the receiver changes customer data, add storage and duplicate checks to your app. If saving fails, return an error so OFAuth can retry.

## Troubleshoot deliveries

Start with the failing stage: reaching your receiver, verifying the signature, or updating application state. Record the HTTP status and processing stage in your receiver's logs. After verification, include `eventId` and `type`, without the signing secret or full event body.

| Symptom | Check | Fix and verify |
| - | - | - |
| Destination remains **Pending** | Did a challenge reach the receiver? Was its response plain text? | Verify the signature first, then return the exact challenge without quotes or a newline. Select **Verify** again and confirm **Verified**. |
| No request reaches the receiver | Is the endpoint current, reachable over HTTPS, and pointing at the right port? | Restart the receiver or tunnel as needed. Update a changed endpoint, then verify it again. |
| Receiver returns `404` | Does the endpoint include `/webhooks/ofauth`? | Correct the path and point the tunnel at port `3001`. |
| This sample returns `400` | Does it have this destination's current secret, the original JSON body, and the three signature headers? | Put the raw-body handler before JSON parsing, update a rotated secret, and check the server clock. |
| A gateway returns `401`, `403`, or a login page | Does a proxy, firewall, or browser login protect the endpoint? | Make the webhook route reachable by OFAuth while keeping signature checks. Repeat destination verification. |
| Destination is verified but no account events arrive | Is it **Active**, in the right environment, with the required events enabled? | Enable it and the needed events. For activity, confirm the account is connected and shared, then trigger the matching action. |
| Receiver returns `2xx`, but application state does not change | Is the handler only logging, or did it accept sample test data? | Save the event first, then add the code that handles its type. Keep sample test data out of customer records. |
| Events repeat | Does storage use `eventId` to identify duplicates? | Return success for duplicates without repeating the action. Test with the same event twice. |
| Old data replaces new data | Are retries arriving after newer events? | Compare `order` for the same linked account, or read the resource's current state. |

The sample logs only the ID and type of accepted events. It does not log challenges or rejected requests. If you add request-stage logs, record statuses rather than secrets or bodies.

### Check reachability separately

For a deployed copy of this sample, send an unsigned request to your endpoint:

```bash theme={null}
curl -i -X POST https://your-receiver.example/webhooks/ofauth \
	-H 'Content-Type: application/json' \
	--data '{}'
```

Expect `400` from this receiver because the signature is missing. That response confirms that the route is reachable and rejects unsigned requests. Use a signed sample event to test acceptance and **Verify** to test delivery from OFAuth.

Next, [receive OnlyFans activity](https://docs.ofauth.com/v3/guides/realtime-onlyfans-events.md) or [handle account reconnects](https://docs.ofauth.com/v3/guides/reconnect.md).


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