# Outbound webhooks

A webhook lets Baton tell your system when something happens, instead of you polling for it. Baton uses Relaystation's account-level webhook registry — you register once, against your customer account, and your registration applies across your batons.

## Registering

```bash
curl -X POST https://api.relaystation.ai/v1/webhooks \
  -H "Authorization: Bearer rs_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-app.example.com/hooks","events":["baton.written","token.used"]}'
```

You provide a delivery URL and the event names you want. Every event payload carries a `baton_id`, so a single endpoint can serve all your batons and filter by id.

## v1 events

Baton v1 fires four event types:

| Event | Fires when |
|---|---|
| `baton.written` | A write — an append or an overwrite — succeeds. |
| `token.used` | A token is used for a read or a write. |
| `token.exhausted` | A token hits its read or write cap. |
| `pass.all_tokens_consumed` | Every recipient of a PASS baton has picked it up. |

More event types — creation, deletion, dormancy, payment, and bundle-limit events — are planned for a later version. Most limit conditions you would want a webhook for (low egress, low time, low writes) are already surfaced as inline warnings on the API responses themselves, so you often do not need a webhook to see them coming.

## Delivery

Deliveries are signed: each carries an `X-Relay-Signature` header, an HMAC you verify with your signing secret to confirm the call really came from Relaystation. Failed deliveries are retried with exponential backoff. A delivery endpoint that keeps failing is eventually disabled — check the Webhooks page in your dashboard for delivery history.

Webhook deliveries fire from a background worker, never inline in your API call — registering a webhook never slows your requests down.