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"| Query | Meaning |
|---|---|
topic | Required. A concrete topic (no wildcards): dot-separated tokens of letters, digits, _, -; at most 128 bytes. 400 otherwise. |
from | Where 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:
| Limit | Default | Maximum |
|---|---|---|
| Events per minute | 600 | 6000 |
| Bytes per hour | 2 MiB | 16 MiB |
| Events per batch | 100 | |
| Bytes per event | 32 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"} }| Status | Meaning |
|---|---|
202 | Accepted: {"accepted": n}. |
400 | Bad JSON, empty events, invalid data, id or ts, or a topic that is not the source’s or an extension of it. |
401 | Missing or wrong key. (All authentication failures look the same.) |
403 | The source is inactive. |
404 | A valid key, but for a different source id. |
413 | Body over 1 MiB, more events than the batch limit, or an event over its size limit. |
429 | Rate limit or byte budget exceeded; Retry-After is 60 or 3600. |
502 | The broker failed mid-batch; accepted says how many were stored. Retry the whole batch (ids make that safe). |
503 | The 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-TimestampandX-Notify-Signature: sha256=<hex>, where the signature isHMAC-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": "…" }