> ## Documentation Index
> Fetch the complete documentation index at: https://onlook.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Receive real-time attention events via HTTP.

## Register a webhook

```bash theme={null}
POST /v1/webhooks
```

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

## Payload shape

```json theme={null}
{
  "id": "evt_7hD1cM3s",
  "type": "score.drop",
  "sessionId": "sess_8xK2mP9q",
  "userId": "alice@acme.com",
  "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:

```ts theme={null}
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 |