Webhooks

Receive real-time attention events via HTTP.

Register a webhook

POST /v1/webhooks

{
  "url": "https://your-backend.com/attention",
  "events": ["score.drop", "score.recover", "session.stopped"],
  "threshold": 40
}

Payload shape

{
  "id": "evt_7hD1cM3s",
  "type": "score.drop",
  "sessionId": "sess_8xK2mP9q",
  "userId": "[e-mail]",
  "score": 34,
  "threshold": 40,
  "timestamp": "2026-04-28T14:32:08Z"
}

Verifying signatures

Every webhook request includes an X-Onlook-Signature header. Verify it to ensure the payload came from OnlookAI:

import { createHmac } from 'crypto'

function verify(payload: string, signature: string, secret: string) {
  const expected = createHmac('sha256', secret)
    .update(payload)
    .digest('hex')
  return `sha256=${expected}` === signature
}

Retry policy

Failed deliveries (non-2xx response or timeout) are retried with exponential backoff: 1m, 5m, 30m, 2h, 8h. After 5 attempts the event is marked failed and logged.

Events

Event	Description
score.drop	Score fell below threshold
score.recover	Score rose above threshold
session.stopped	Session ended
intervention.fired	Intervention triggered
intervention.resolved	User answered or dismissed