Events and webhooks

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.

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.

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.

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

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.