# Events and webhooks

Read what happened as a stream, or have signed events sent to your own https endpoint.

## Read the event stream

Rivier records an event when something changes: a key is made, a message is delivered, a message bounces. `GET /events` reads events from a cursor, limited to the areas the key can read. `GET /events/stream` is the same as a server-sent stream; reconnect with `Last-Event-ID` to carry on where you stopped. `GET /events/catalogue` lists every event type and the operation that raises it.

Request:

```
curl -sS -N https://api.rivier.ai/events/stream \
  -H "Authorization: Bearer $RIVIER_API_KEY"
```

## Register a webhook

`POST /webhooks/endpoints` registers an https address and the event types it takes; a pattern such as `inbox.message.*` takes a whole family. The signing secret is in the answer once. Making and removing endpoints needs `keys:admin`.

Request:

```
curl -sS https://api.rivier.ai/webhooks/endpoints \
  -H "Authorization: Bearer $RIVIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/hooks/rivier", "events": ["inbox.message.*"] }'
```

## Check the signature

Each delivery carries `X-Rivier-Signature` with a time and an HMAC-SHA256 of the time, a full stop and the raw body, keyed with the endpoint secret. Compute it over the body exactly as received, before parsing, compare in constant time, and refuse a time more than five minutes old.

Header:

```
X-Rivier-Signature: t=1762776000,v1=5f2b…
```

TypeScript:

```
import { verifyWebhook } from "@rivier/sdk";

verifyWebhook({
  secret: process.env.RIVIER_WEBHOOK_SECRET,
  rawBody,
  signature: request.headers.get("x-rivier-signature"),
});
```

## Deliveries and replay

`GET /webhooks/deliveries` is the log: each attempt, what your endpoint answered and what is waiting to be tried again. An endpoint that keeps failing is switched off; `POST /webhooks/endpoints/{id}/enable` switches it back on, and the replay routes send one delivery or everything from a point in the stream again. Deliveries can arrive more than once, so use the event id to ignore repeats.