Events

Event stream

GET /v1/events/stream tails your workspace's events as they happen, over Server-Sent Events. Each envelope-event frame carries the same JSON a webhook endpoint receives, including mode. Reuse your payload-processing code when reading SSE. To exercise an unchanged HTTP webhook handler, use senv webhook tail --forward http://localhost:3000/webhook --secret YOUR_LOCAL_SECRET; the CLI converts events into signed HTTP POSTs.

Open a stream

curl -N https://app-staging.signenvoy.com/v1/events/stream \
  -H "Authorization: Bearer $SENV_API_KEY" \
  -H "Accept: text/event-stream"

retry: 3000

event: ready
data: {"cursor": 418, "mode": "test"}

id: 419
event: document.sent
data: {"id":"evt_outbox_419","type":"document.sent","created_at":"2026-08-22T12:00:00+00:00","document":"doc_...","data":{"seq":2,"engine_event_type":"sent","actor":{"type":"api"}},"mode":"test"}

: keep-alive

The ready frame tells you where the tail starts. A fresh stream begins at the newest event, so you see what happens next rather than a replay. The key's mode scopes the stream: a test key sees test envelopes only, a live key live envelopes only.

Resume and filter

Send Last-Event-ID (the last id: you saw) when reconnecting, or ?after_id=N, to resume strictly after that event. Events older than the seven-day outbox retention are gone.
?events=document.completed,document.sealed limits the stream to those types; unknown types answer validation-failed.

Lifecycle frames

: keep-alive every 15 seconds while nothing happens.
event: reconnect after 15 minutes: the server closes the stream on purpose. Reconnect immediately with Last-Event-ID; this is a rotation, not a failure, so do not back off.
event: error with a problem body, then the stream closes: reconnect after retry milliseconds with backoff.

Limits

Five concurrent streams per workspace; a sixth answers rate-limited with Retry-After: 5. The stream carries the usual X-SignEnvoy-Envelopes-This-Period and rate-limit headers.