CORE

OnlyFans Webhooks — Event Reference

OnlyFans webhooks deliver real-time event notifications to your server the moment something happens on a connected creator account. New subscriber? Revenue event? Expired subscription? Incoming message? Your server receives a signed JSON payload within seconds. Webhooks are the foundation for every integration — Slack alerts, Google Sheets syncs, Zapier automations, and custom dashboards all start here.

On This Page

Event Types

Subscribe to one or more of the following event types. Each event fires a POST request to your registered webhook URL with a JSON payload containing the event name and associated data.

EVENT subscriber.new
EVENT subscriber.expired
EVENT revenue.received
EVENT message.received

Payload Schemas

Every webhook payload follows a consistent envelope structure. The event field identifies the type, and data contains the event-specific fields.

subscriber.new

subscriber.new payload JSON 
{
  "event": "subscriber.new",
  "timestamp": "2026-03-06T14:22:31Z",
  "data": {
    "creator": "luna_model",
    "creator_id": "creator_abc123",
    "username": "fan_user_42",
    "user_id": "user_789xyz",
    "subscription_price": 9.99,
    "subscription_type": "recurring",
    "started_at": "2026-03-06T14:22:31Z",
    "expires_at": "2026-04-06T14:22:31Z"
  }
}

subscriber.expired

subscriber.expired payload JSON 
{
  "event": "subscriber.expired",
  "timestamp": "2026-03-06T14:30:00Z",
  "data": {
    "creator": "luna_model",
    "creator_id": "creator_abc123",
    "username": "fan_user_17",
    "user_id": "user_456def",
    "subscribed_since": "2025-12-06T10:00:00Z",
    "expired_at": "2026-03-06T14:30:00Z",
    "total_spent": 147.50,
    "renewal_count": 2
  }
}

revenue.received

revenue.received payload JSON 
{
  "event": "revenue.received",
  "timestamp": "2026-03-06T15:01:12Z",
  "data": {
    "creator": "luna_model",
    "creator_id": "creator_abc123",
    "username": "fan_user_42",
    "type": "tip",
    "amount": 47.50,
    "net_amount": 38.00,
    "currency": "USD",
    "description": "Tip from fan_user_42"
  }
}

message.received

message.received payload JSON 
{
  "event": "message.received",
  "timestamp": "2026-03-06T15:10:44Z",
  "data": {
    "creator": "luna_model",
    "creator_id": "creator_abc123",
    "from_user": "fan_user_42",
    "from_user_id": "user_789xyz",
    "message_id": "msg_abc987",
    "text": "Hey, love your content!",
    "has_media": false,
    "is_paid": false
  }
}

Setup Guide

1

Register Your Endpoint

In the OFAPI dashboard, go to Settings → Webhooks. Click Add Endpoint and enter the URL of your server that will receive webhook events. Select which events to subscribe to — you can always change this later.

2

Build Your Handler

Your endpoint must accept POST requests with a JSON body and respond with a 200 status code within 10 seconds. Here is a minimal example:

webhook_handler.py Python 
import hmac, hashlib, os
from flask import Flask, request, jsonify

app = Flask(__name__)
SECRET = os.environ["OFAPI_WEBHOOK_SECRET"]

def verify_signature(payload_body, signature):
    expected = hmac.new(
        SECRET.encode(), payload_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

@app.route("/webhook", methods=["POST"])
def handle():
    sig = request.headers.get("X-OFAPI-Signature", "")
    if not verify_signature(request.data, sig):
        return jsonify({"error": "invalid signature"}), 401

    payload = request.json
    event   = payload["event"]
    data    = payload["data"]

    # Route to your handler
    if event == "revenue.received":
        handle_revenue(data)
    elif event == "subscriber.new":
        handle_new_sub(data)
    elif event == "subscriber.expired":
        handle_churn(data)
    elif event == "message.received":
        handle_message(data)

    return jsonify({"ok": True}), 200
3

Send a Test Event

Use the Send Test Event button in the OFAPI dashboard to fire a sample payload to your endpoint. Check your server logs to confirm it was received and processed correctly.

Security & Signature Verification

Every webhook request includes an X-OFAPI-Signature header containing an HMAC-SHA256 hash of the request body signed with your webhook secret. Always verify this signature before processing the payload to prevent spoofed events.

Your webhook secret is shown once when you create the endpoint in the OFAPI dashboard. Store it securely in an environment variable. If compromised, rotate it from the dashboard immediately.

Retry Policy

If your endpoint does not respond with a 2xx status within 10 seconds, the delivery is considered failed. Failed deliveries are retried with exponential backoff:

Retry 1 30 seconds after initial failure
Retry 2 5 minutes after first retry
Retry 3 30 minutes after second retry
Retry 4 2 hours after third retry
Retry 5 24 hours after fourth retry (final attempt)

After 5 failed attempts, the event is marked as undelivered and visible in the OFAPI dashboard under Webhooks → Failed Deliveries. You can manually retry any failed event from there.

Integration

Slack Alerts →

Integration

Discord Alerts →

Reference

API Docs →

Real-time data, delivered to your server

Webhooks are available on Pro and Enterprise plans. Start receiving events in minutes.

View Pricing → Read the Docs