Real-time events for everything.

Receive real-time notifications when users earn, withdraw, agents complete, and more.

// Events

Available webhook events

Event	Trigger	Payload includes
`earn.completed`	User earns from /v1/earn/1 or /v1/route	user_id, earned_pence, worm_seal
`withdrawal.initiated`	POST /v1/withdraw called	user_id, amount_pence, stripe_transfer
`withdrawal.failed`	Stripe transfer fails — balance restored	user_id, error, record_id
`agent.completed`	Agent task finishes	task_id, agent_id, duration_ms
`agent.failed`	Agent task exceeds retries	task_id, error, retries
`signup.created`	New user signs up	user_id, referral_code
`fraud.blocked`	Payout blocked by fraud layer	user_id, reason, risk_level

// Payload format

Webhook payload structure

All webhooks are POST requests with a JSON body. Every payload includes a WORM seal for verification.

Example: earn.completed

{
  "event": "earn.completed",
  "ts": 1747043200000,
  "data": {
    "user_id": "usr_1e09b31d...",
    "task": "summarise_sentence",
    "earned_pence": 78,
    "earned_gbp": "£0.78",
    "balance_pence": 156,
    "worm_seal": "c2e91c81...",
    "record_id": "earn1-986ef5fe..."
  }
}

// Register endpoint

Register your webhook

cURL

curl -X POST https://api.forcedream.ai/v1/webhooks \
  -H "Authorization: Bearer $FD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/forcedream",
    "events": ["earn.completed","withdrawal.initiated"],
    "secret": "your_webhook_secret"
  }'

Verify webhook authenticity: check the X-ForceDream-Signature header against HMAC-SHA256 of the payload body using your webhook secret.