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

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.