Skip to content
Streams and webhooks

Streams and webhooks

Three ways to move events in and out of notify besides messages to people: a durable feed you can subscribe to, stream sources that push events into it, and outbound webhooks that carry delivery events to your servers.

The feed

The feed is a durable JetStream stream per environment. Two things write to it: the stream step, and stream sources. Read it as Server-Sent Events:

curl -N "localhost:3000/v1/feed/stream?topic=orders.eu&from=2026-10-18T00:00:00Z" \
  -H "Authorization: ApiKey $KEY"
QueryMeaning
topicRequired. A concrete topic (no wildcards): dot-separated tokens of letters, digits, _, -; at most 128 bytes. 400 otherwise.
fromWhere to start: a stream sequence number or an RFC 3339 time. Absent means live only.

To resume after a disconnect, send Last-Event-ID with the last event id you saw; it takes precedence over from. Unlike the inbox stream, the feed is lossless: a client that falls too far behind is disconnected rather than silently dropped, and it resumes where it left off. The environment comes only from your API key.

Two payload shapes share the feed, told apart by the v key. A stream step publishes the message JSON ({"Channel": "stream", …}); a source publishes the envelope below.

Stream sources

A stream source lets an external system push events into the feed without an API key. It holds a SourceKey secret that works for one endpoint only.

Sources are created and managed in the console (Stream sources): create, rotate the key, set limits, deactivate, delete. The secret is shown when you create or rotate it. Defaults and ceilings:

LimitDefaultMaximum
Events per minute6006000
Bytes per hour2 MiB16 MiB
Events per batch100
Bytes per event32 KiB

A source has a base topic; a producer may publish to that topic or any dot-extension of it.

Pushing events

curl -X POST localhost:3000/v1/sources/$SOURCE_ID/events \
  -H "Authorization: SourceKey $SOURCE_KEY" -H 'Content-Type: application/json' \
  -d '{"topic": "builds.api", "events": [{"id": "run-881", "ts": "2026-10-18T12:00:00Z", "data": {"status": "passed"}}]}'

topic is optional (defaults to the source topic). Each event has data (required, any JSON) and optional id (up to 128 characters of A-Za-z0-9_-; makes the event deduplicated, so a retry is safe) and ts (RFC 3339; stamped now if absent). Consumers receive:

{ "v": 1, "source_id": "01J…", "event_id": "run-881", "ts": "2026-10-18T12:00:00Z", "data": {"status": "passed"} }
StatusMeaning
202Accepted: {"accepted": n}.
400Bad JSON, empty events, invalid data, id or ts, or a topic that is not the source’s or an extension of it.
401Missing or wrong key. (All authentication failures look the same.)
403The source is inactive.
404A valid key, but for a different source id.
413Body over 1 MiB, more events than the batch limit, or an event over its size limit.
429Rate limit or byte budget exceeded; Retry-After is 60 or 3600.
502The broker failed mid-batch; accepted says how many were stored. Retry the whole batch (ids make that safe).
503The limiter is unavailable.

Every rejection happens before anything is published.

Outbound webhooks

Outbound webhook endpoints receive delivery events: the message JSON of every terminal channel result (sent, error, skipped, throttled), email.reply events from the reply loop, and the SMS events sms.inbound, sms.opt_out, sms.opt_in and sms.status. Events other than message JSON carry a type.

curl -X POST localhost:3000/v1/webhooks/endpoints \
  -H "Authorization: ApiKey $KEY" -H 'Content-Type: application/json' \
  -d '{"url": "https://hooks.acme.test/notify", "active": true}'

The response includes the endpoint (id, url, active, signed) and, once, its signing secret. POST /v1/webhooks/endpoints/{id}/secret rotates it and returns the new one; endpoints that predate signing get their first secret this way. Management routes are in the API reference.

Delivery

Each event is POSTed as JSON to every active endpoint in the event’s environment.

  • Signature. Headers X-Notify-Timestamp and X-Notify-Signature: sha256=<hex>, where the signature is HMAC-SHA256(secret, timestamp + "." + body). Every attempt is signed afresh. Reject events whose timestamp is too old to bound replay.
  • At least once. Events are consumed from a durable JetStream consumer, so events published while notify is down are delivered when it comes back.
  • Per-endpoint retry. A failed POST is retried with exponential backoff (5 seconds, doubling, capped at 30 minutes) for up to 12 attempts, about an hour and three quarters, then dropped with an error log. Retries are per endpoint and survive restarts; an endpoint that is down does not delay the others.
  • Disabled or deleted endpoints drop their pending deliveries.
  • SSRF guard. URLs are checked at connect time like other tenant-supplied URLs (details).

An email.reply event:

{ "type": "email.reply", "subscriberId": "user-1", "transactionId": "…", "workflow": "order-shipped",
  "notificationId": "…", "text": "Thanks!", "from": "ada@example.com", "messageId": "<…>", "receivedAt": "…" }

An sms.inbound event. subscriberId is absent when no subscriber has the sender’s phone; phoneVerified is false when the match has not verified it. sms.opt_out and sms.opt_in have the same shape plus keyword (STOP, START, …), one per subscriber with the number (or one with no subscriberId), sent only when the opt-out actually changed:

{ "type": "sms.inbound", "subscriberId": "user-1", "phoneVerified": true, "from": "+15551112222",
  "to": "+15559990000", "body": "Running late", "integrationId": "…", "providerId": "twilio",
  "providerMessageId": "SM…", "inboundMessageId": "…", "receivedAt": "…" }

An sms.status event, sent when a delivery-status callback moves a message to delivered or error:

{ "type": "sms.status", "messageId": "…", "status": "error", "errorClass": "recipient",
  "errorText": "twilio: undelivered (error 30003)", "subscriberId": "user-1", "notificationId": "…",
  "transactionId": "…", "workflowId": "…", "integrationId": "…", "providerMessageId": "SM…", "updatedAt": "…" }