Skip to content
nofeb

Product / Events and webhooks

Events, streams and hooks

Agents work by reacting. nofeb tells you what happened as a typed event, in three ways that suit different consumers, lets your code decide what happens to a message or a send while it is in flight, and makes every call that changes something safe to retry.

Signed webhooks that cannot leak across tenants

Webhooks are signed per the Standard Webhooks specification, retried on failure, and every attempt is kept in a delivery log you can read. Every subscription must state its scope: the organization, one pod or one inbox. A subscription with no scope is refused rather than widened to everything, so a missing field cannot send one customer's mail events to another's endpoint.

The SDKs verify deliveries for you: verifyWebhook in @nofeb/sdk checks the signature against the raw body and refuses timestamps more than five minutes off.

Subscribe one inbox
POST /v1/webhooks
{ "url": "https://example.com/nofeb/events",
  "events": ["message.received", "approval.requested"],
  "scope": "inbox", "inbox_id": "inb_..." }

A feed for consumers without a public URL

The event feed returns the same events after a cursor, durably, for workers behind a firewall, batch jobs and agents that would rather pull than be called. Filter it by inbox or thread, or read it newest first.

A stream for clients that stay connected

The WebSocket stream carries the same events as webhooks and the feed, in the same order, each with a cursor. Reconnect with the last cursor and the stream resumes with no gap and no duplicates; a cursor older than the feed keeps is refused rather than silently skipped. Narrow it by inbox, pod or event type, never wider than the credential allows. A client that falls too far behind is disconnected without slowing anyone else, and a revoked credential is cut off at the next heartbeat.

Stream one inbox's mail events
GET wss://API_HOST/v1/stream?inbox_id=inb_...&types=message.*
Sec-WebSocket-Protocol: nofeb.v1

{ "type": "event", "cursor": "...", "event": { "type": "message.received", ... } }

Hooks that decide, inside the pipeline

Hooks are called while mail is in flight and change what happens: at inbound.resolve, create an inbox for an unknown recipient or refuse it; at inbound.pre_deliver, accept, reject or quarantine a message and add keywords and metadata; at outbound.pre_send, allow, deny or hold a send and add headers. Each hook has a timeout and fails open or closed, and every call is logged.

A hook can be an HTTPS endpoint, signed like a webhook, or a WebAssembly module that runs inside the pipeline with no network round trip. Modules are built against a published, versioned interface, receive the same request and give the same answer as an HTTPS hook, and run sandboxed with limits on instructions, memory and time. A module can log, read and set metadata on what it is deciding about, and fetch only the URLs you allow. Upload new versions as you go; the last ten are kept for rollback.

A WebAssembly pre-delivery hook
POST /v1/hooks
{ "stage": "inbound.pre_deliver", "target": "wasm",
  "scope": "inbox", "inbox_id": "inb_...",
  "allow_urls": ["https://crm.example.com/api/"],
  "failure_mode": "fail_open" }

POST /v1/hooks/{hook_id}/module
Content-Type: application/wasm
<component bytes>

Events on a schedule you set

Not every event is caused by mail. Set follow_up_at on a thread and a thread.due event arrives through the same webhooks, feed and stream when that time passes, with the thread's metadata attached, so an agent can be woken by the clock as well as by a reply.

The event catalog

Event types are added, never renamed. Events with a known actor say whether an agent, a person, the console or the system acted, and mail events name their inbox and thread.

EventMeaningStatus
message.receivedAn inbound message was delivered to an inbox.Shipped
message.quarantinedAn inbound message was held for review: injection score, a hook, a rule, a sender list, spam, virus or DMARC.Shipped
message.releasedA person released a quarantined message to the inbox.Shipped
message.sentAn outbound message was accepted for delivery.Shipped
message.deliveredThe recipient's server accepted the message.Shipped
message.bouncedThe message bounced.Shipped
message.complainedThe recipient marked the message as spam.Shipped
message.send_failedAn outbound message failed permanently.Shipped
metadata.updatedMetadata on a message, thread or inbox changed.Shipped
approval.requestedA send is waiting for human approval.Shipped
approval.decidedA pending send was approved or rejected.Shipped
inbox.createdAn inbox was created.Shipped
inbox.expiredA disposable inbox reached its expiry and was removed.Shipped
thread.dueA thread's follow_up_at time passed.Shipped
thread.driver_changedA person took a thread over from the agent, or handed it back.Shipped
domain.verifiedA custom domain passed DNS verification.Shipped
policy.violatedA governance policy refused a send (blocklist, allowlist or cap) or an inbound message (sender list).Shipped
message.rejectedAn inbound message was not delivered because a sender blocklist or a rule rejected it.Shipped
forward.confirmationA Gmail or Outlook forwarding confirmation arrived on a forwarding address, with its code and link.Shipped
export.completedAn export finished; it carries signed download links.Shipped
export.failedAn export could not be built.Shipped
retention.appliedA retention policy moved or deleted messages.Shipped
sending.pausedOutbound sending for the organization was paused, because the bounce or complaint rate crossed its threshold or on request.Shipped
sending.resumedOutbound sending for the organization was resumed.Shipped
calendar.event.createdA calendar event was created.Shipped
calendar.event.updatedA calendar event, or one occurrence, changed or was answered.Shipped
calendar.event.deletedA calendar event was deleted.Shipped
calendar.event.invitedAn invitation, or an update to one, arrived by email and is on the calendar.Shipped
calendar.event.cancelledThe organizer cancelled an event, or one occurrence.Shipped
calendar.event.repliedA guest answered an event this inbox organizes.Shipped
calendar.event.counter_proposedA guest proposed a new time for an event this inbox organizes.Shipped
calendar.changedA calendar was created, changed or deleted.Shipped

Status of everything on this page

Every capability named above, with its status as reconciled against the engine.

CapabilityWhat it doesStatus
Signed webhooks with required scope Standard Webhooks signatures, retries and a delivery log. Scope (organization, pod or inbox) is required, so a subscription never silently widens to everything. Shipped
Durable event feed A pull feed of every event, oldest first after a cursor, for consumers that cannot receive webhooks. Shipped
Realtime stream A WebSocket stream of the same events as webhooks and the feed, in order, resumable from a cursor with no gap and no duplicates, and filtered by inbox, pod or event type within the credential's own reach. Shipped
HTTPS hooks in the pipeline Signed HTTPS callouts that change what happens: create or reject an inbox for an unknown recipient, accept, reject or quarantine a message before delivery, and allow, deny or hold a send, each with a timeout and a fail-open or fail-closed mode. Shipped
WebAssembly hooks The same pipeline stages as HTTPS hooks, run as a WebAssembly module you upload, built against a published, versioned interface. Modules run sandboxed with fuel, memory and time limits, can fetch only the URLs you allow, read and set metadata on what they decide about, and keep their last ten versions for rollback. Shipped
Follow-up timers Set follow_up_at on a thread and, when that time passes, a thread.due event carrying the thread's metadata goes to your webhooks and the event feed, so agents need no scheduler of their own. Shipped
Change log per inbox Every change to an inbox since a state you already hold, for sync without re-reading. Shipped
Idempotent sends Retry a send with the same Idempotency-Key and it is sent once. Shipped
OpenAPI document A published OpenAPI document kept identical to the served routes by a parity test. Shipped
Published plan table The plan table and overage prices are served publicly by the API, and this site's pricing is checked against it. Shipped
TypeScript and Python SDKs Official clients generated from the OpenAPI document: @nofeb/sdk for Node, Deno, Bun and edge runtimes, and nofeb for Python with sync and asyncio clients. Both chain long polls for waitForEmail, retry idempotent requests, page through lists and verify webhook signatures. Shipped