Webhook Integration

Webhooks allow you to receive real-time HTTP notifications when events occur in your OnlyMonster account. Instead of polling for changes, your server receives a POST request with event data as soon as something happens.

Note: Webhook event types are currently in active development. This page will be updated as new events become available.

Setup

1. Log in to your OnlyMonster dashboard

2. Navigate to API → Webhooks

3. Enter your HTTPS endpoint URL and click Save

4. Copy and securely store the webhook secret

Important: The webhook secret is displayed only once. Save it in a secure location immediately. If you lose it, you will need to create a new webhook.

You can view or delete your active webhook from the same API → Webhooks tab.

Note: It can take up to 1 minute after you save a new webhook before events start being delivered.

Receiving Webhooks

When an event occurs, OnlyMonster sends an HTTP POST request to your configured URL with the following headers:

Header	Description
content-type	Always application/json
x-om-webhook-signature	HMAC-SHA256 hex-encoded signature
x-om-webhook-timestamp	ISO 8601 timestamp of when the event was sent
x-om-webhook-id	UUID unique to this delivery attempt — use it for deduplication if you process retries

Payload Format

The request body is a JSON object with the following structure:

{
  "type": "event_type",
  "payload": {
    ...
  }
}

• type — a string identifying the event (e.g. chat.message, chat.message_sent)

• payload — an object containing event-specific data

Verifying Signatures

Every webhook request is signed using your secret so you can verify it was sent by OnlyMonster and hasn't been tampered with.

To verify a webhook signature:

1. Get the x-om-webhook-timestamp and x-om-webhook-signature headers from the request

2. Construct the signed content by concatenating the timestamp, a dot (.), and the raw request body:

   {x-om-webhook-timestamp}.{raw_request_body}

3. Compute an HMAC-SHA256 hash of the signed content using your webhook secret

4. Compare the hex-encoded result with x-om-webhook-signature

Node.js / TypeScript

import { createHmac, timingSafeEqual } from 'node:crypto'

function verifyWebhookSignature(
  rawBody: string,
  signature: string,
  timestamp: string,
  secret: string,
): boolean {
  const payload = `${timestamp}.${rawBody}`
  const expected = createHmac('sha256', secret).update(payload).digest('hex')

  return timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
}

// Usage (Express example)
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-om-webhook-signature'] as string
  const timestamp = req.headers['x-om-webhook-timestamp'] as string
  const rawBody = req.body.toString()

  if (!verifyWebhookSignature(rawBody, signature, timestamp, WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature')
  }

  const event = JSON.parse(rawBody)
  // Process event...

  res.status(200).send('OK')
})

Go

package main

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"fmt"
	"io"
	"net/http"
)

func verifyWebhookSignature(rawBody, signature, timestamp, secret string) bool {
	payload := fmt.Sprintf("%s.%s", timestamp, rawBody)
	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write([]byte(payload))
	expected := hex.EncodeToString(mac.Sum(nil))

	return hmac.Equal([]byte(signature), []byte(expected))
}

func webhookHandler(w http.ResponseWriter, r *http.Request) {
	body, err := io.ReadAll(r.Body)
	if err != nil {
		http.Error(w, "Bad request", http.StatusBadRequest)
		return
	}

	signature := r.Header.Get("x-om-webhook-signature")
	timestamp := r.Header.Get("x-om-webhook-timestamp")

	if !verifyWebhookSignature(string(body), signature, timestamp, webhookSecret) {
		http.Error(w, "Invalid signature", http.StatusUnauthorized)
		return
	}

	// Process event...

	w.WriteHeader(http.StatusOK)
	w.Write([]byte("OK"))
}

Event Types

All events follow a consistent structure:

{
  "type": "<category>.<action>",
  "payload": {
    // event-specific fields
  }
}

The Source column in the field tables indicates whether a value originates from OnlyFans (so it follows OnlyFans formats and lifecycle — IDs match what you'd see in the OF API) or from OnlyMonster (identifiers and metadata generated on our side).

Shared payload.account object

Account-scoped events (e.g. chat.message, vault.media_upload.created, vault.media_upload.updated) include an account object on payload that identifies which account the event belongs to:

Field	Type	Source	Description
account_id	string	OnlyMonster	OnlyMonster account ID — stable across platform reconnects.
platform_account_id	string	OnlyFans	OnlyFans user ID of the connected account (your account, not the fan's).

chat.message

Fires when a chat message is observed on one of your connected OnlyFans accounts. This includes both messages a fan sends to you and messages sent from your account to a fan.

Example:

{
  "type": "chat.message",
  "payload": {
    "account": {
      "account_id": "acc_01HZY...",
      "platform_account_id": "11122233"
    },
    "message": {
      "message_id": "1234567890",
      "fan_id": "987654321",
      "from_id": "987654321",
      "created_at": "2026-04-27T10:00:00.000Z",
      "text": "Hi!",
      "medias": {
        "55501": { "type": "photo" }
      }
    }
  }
}

Fields (payload):

Field	Type	Source	Description
account	object	mixed	Identifies the account this event belongs to. See the shared payload.account table above.
message	object	OnlyFans	The chat message. See payload.message fields below.

Fields (payload.message):

Field	Type	Source	Description
message_id	string	OnlyFans	OnlyFans message ID.
fan_id	string	OnlyFans	OnlyFans user ID of the fan in the conversation (always the other party — never your own account).
from_id	string	OnlyFans	OnlyFans user ID of the sender.
created_at	string (ISO 8601)	OnlyFans	When the message was created on OnlyFans.
text	string | null	OnlyFans	Message text. null for media-only messages.
medias	Record<string, { type: string }>	OnlyFans	Map of attached media keyed by OnlyFans media ID. Each value contains the media type (e.g. "photo", "video", "gif", "audio").

Determining message direction:

The payload does not include an explicit direction field. Compare from_id and fan_id to tell incoming from outgoing:

• from_id === fan_id → incoming — the fan sent the message to you.

• from_id !== fan_id → outgoing — you sent the message to the fan.

Restored messages:

If our connection to OnlyFans is briefly lost, missed activity is reconciled when the connection is restored. For each chat that had new activity during the outage, we deliver only the most recent message in that chat — intermediate messages sent during the outage are not backfilled. These deliveries include an additional metadata object on the payload:

{
  "type": "chat.message",
  "payload": {
    "account": { "...": "..." },
    "message": { "...": "..." },
    "metadata": {
      "is_restored": true,
      "connection_lost_at": "2026-04-27T09:55:00.000Z"
    }
  }
}

Field	Type	Source	Description
is_restored	boolean (optional)	OnlyMonster	true when the message was backfilled after a brief disconnect rather than received in real time.
connection_lost_at	string (ISO 8601, optional)	OnlyMonster	When the disconnect started — bounds the period these restored messages cover.

For restored messages, medias is delivered as an empty object ({}) — media metadata is not available from the backfill source.

chat.message_sent

Fires when a message you submitted via the OnlyMonster API is successfully delivered to OnlyFans. This event is only sent for messages you submit through the public API — messages sent by other OnlyMonster features do not trigger this webhook.

Example:

{
  "type": "chat.message_sent",
  "payload": {
    "send_id": "snd_01HZX...",
    "account_id": "acc_01HZY...",
    "fan_id": "987654321",
    "platform_message_id": "1234567890"
  }
}

Fields (payload):

Field	Type	Source	Description
send_id	string	OnlyMonster	Identifier returned to you when you submitted the send request — use it to correlate.
account_id	string	OnlyMonster	OnlyMonster account ID the message was sent from.
fan_id	string	OnlyFans	OnlyFans user ID of the recipient.
platform_message_id	string	OnlyFans	OnlyFans message ID assigned to the delivered message. The corresponding chat.message event for this delivery will carry the same value in payload.message.message_id.

chat.message_error

Fires when a message you submitted via the OnlyMonster API fails to be delivered to OnlyFans. As with chat.message_sent, this event is only sent for messages submitted through the public API.

Example:

{
  "type": "chat.message_error",
  "payload": {
    "send_id": "snd_01HZX...",
    "account_id": "acc_01HZY...",
    "fan_id": "987654321",
    "status": "restricted"
  }
}

Fields (payload):

Field	Type	Source	Description
send_id	string	OnlyMonster	Identifier returned to you when you submitted the send request — use it to correlate.
account_id	string	OnlyMonster	OnlyMonster account ID the message was attempted from.
fan_id	string	OnlyFans	OnlyFans user ID of the intended recipient.
status	"restricted" | "failed"	OnlyMonster	restricted — the recipient has blocked or restricted messages. failed — any other delivery failure.

vault.media_upload.created

Fires when a new media upload is created in your OnlyMonster vault. The upload starts in the uploaded state and transitions through processing/exporting states; subsequent transitions are delivered as vault.media_upload.updated events.

Example:

{
  "type": "vault.media_upload.created",
  "payload": {
    "media_upload_id": "a3f8c9b1-7e2d-4f8a-9b6c-1d2e3f4a5b6c",
    "media_id": null,
    "status": "uploaded",
    "account": {
      "account_id": "acc_01HZY...",
      "platform_account_id": "11122233"
    },
    "created_at": "2026-04-27T10:00:00.000Z",
    "updated_at": "2026-04-27T10:00:00.000Z"
  }
}

Fields (payload):

Field	Type	Source	Description
media_upload_id	string	OnlyMonster	Stable OnlyMonster identifier for this upload — use it to correlate created and subsequent updated events.
media_id	string | null	OnlyFans	OnlyFans media ID assigned once the upload has been exported to the platform. null until export completes.
status	string (enum)	OnlyMonster	Current upload state. One of uploaded, processing, processed, exporting, exported, failed, unprocessable.
account	object	mixed	Identifies the account this upload belongs to. See the shared payload.account table above.
created_at	string (ISO 8601)	OnlyMonster	When the upload row was created.
updated_at	string (ISO 8601)	OnlyMonster	When the upload row was last persisted. Equal to created_at for a freshly created upload.

Note: Ordering and dedup guidance is shared with vault.media_upload.updated below — read it before storing state.

vault.media_upload.updated

Fires on any persisted change to an existing vault media upload — most commonly a status transition (e.g. processing → processed) or an assignment of media_id once the upload is processed.

Important:

• Consumers should not assume a specific delta from a single event — read status (and media_id) on every event and reconcile against media_upload_id.

• Events for the same media_upload_id may arrive out of order. Order them by updated_at before applying — do not flip a stored status backward just because a newer event was received first.

• Vault events may be delivered more than once (e.g. when a previous attempt's response was lost in flight) — treat (media_upload_id, updated_at) as the dedup key. x-om-webhook-id changes on every retry attempt and is not suitable for cross-retry deduplication.

Example:

{
  "type": "vault.media_upload.updated",
  "payload": {
    "media_upload_id": "a3f8c9b1-7e2d-4f8a-9b6c-1d2e3f4a5b6c",
    "media_id": "55501",
    "status": "processed",
    "account": {
      "account_id": "acc_01HZY...",
      "platform_account_id": "11122233"
    },
    "created_at": "2026-04-27T10:00:00.000Z",
    "updated_at": "2026-04-27T10:00:30.000Z"
  }
}

Fields (payload): Same as vault.media_upload.created above. updated_at advances on each transition.

Retry & Delivery Behavior

Behavior	Details
Timeout	15 seconds per request
Retries	Up to 3 attempts with 15-second delay
Retry condition	5xx server errors and network failures
No retry	2xx (success), 3xx, 4xx responses
Redirects	Not followed

Your endpoint must respond with an HTTP 2xx status code to acknowledge receipt. Any 5xx response or network failure will trigger a retry.

Backpressure during sustained timeouts

To protect both your endpoint and our delivery pipeline, we apply per-organisation backpressure when your endpoint stops responding entirely. If your endpoint times out (no response within the 15-second window) on several consecutive deliveries, we temporarily pause delivery for ~1 minute. Events that fire during the pause window are dropped — not retried. After the pause, we send a single probe; if it succeeds, normal delivery resumes immediately, otherwise the pause renews.

Backpressure is triggered only by request timeouts. 5xx responses, network errors (e.g. connection refused, DNS), and SSRF/HTTP-blocked targets do not trigger it — they follow the standard retry table above.

If you need a complete history of events, treat webhooks as a real-time signal and reconcile against the corresponding polling endpoints periodically. Backpressure pauses are observable on your side as a gap with no delivery attempts.

Best Practices

• Verify signatures — Always verify the x-om-webhook-signature before processing any event to ensure authenticity.

• Respond quickly — Return a 200 response immediately, then process the event asynchronously. Long-running processing may cause timeouts.

• Use HTTPS — Webhook URLs must use HTTPS. HTTP endpoints are rejected.

• Secure your secret — The webhook secret is shown only once during setup. Store it in a secrets manager or environment variable.