Follow each delivery, safely.
Three independent paths
| Path | Authentication | Purpose |
|---|---|---|
| Provider → Notifications | Provider-specific signatures; connection and credential revision where applicable. | Normalize delivery, read and failure receipts. |
| Notifications → your backend | Native HMAC-SHA256, timestamp and stable event ID. | Durable at-least-once business delivery events. |
| Notifications → authorized browser | Short-lived inbox grant in Authorization header. | SSE change hints followed by an authorized inbox read. |
Provider receipt signatures
POST /v1/provider-webhooks/{providerId} accepts the provider’s JSON or form receipt. Set the
provider-specific signature headers, not a Notifications API key. For a tenant-owned number, use the exact
callback URL returned by its connection.
-
Twilio:
X-Twilio-Signature, verified against the exact callback URL and sorted form parameters. - Meta:
X-Hub-Signature-256over raw body bytes. -
Zavu:
X-Zavu-Signature, timestampedv2HMAC. Older/unrecognized formats are rejected. - Resend:
svix-id,svix-timestampandsvix-signature.
The explicit fake runtime has a synthetic receipt signature for local contract tests. Real adapters never accept that signature. Webhook verification uses pinned sender authority for late receipts; rotation does not authorize another tenant’s message.
Outbound signature
Your operator registers the organization’s outbound endpoint and vault-held signing secret. This is not a public endpoint-registration API. The receiver must preserve the raw request bytes.
x-anam-event-id: <stable-event-id> x-anam-event-type: message.delivered x-anam-tenant: ref:workspace-001 x-anam-timestamp: <unix-seconds> x-anam-signature: t=<unix-seconds>,v1=<hex-hmac> signed material = timestamp + "." + rawBody algorithm = HMAC-SHA256
Reject timestamps outside ±300 seconds and malformed signatures; compare fixed-length digests in constant time. Accept current and previous vault secrets only for the documented rotation window. Deduplicate by event ID, commit durable work, respond 2xx promptly, and process asynchronously.
Events can arrive out of order. Reconcile with GET /v1/messages/{id}; never move a delivered
message backwards because a sent event arrived late. A retry preserves the event ID.
Event contracts
Message events: accepted, scheduled, rescheduled, cancelled, sent, delivered, read, failed and suppressed. Recipient events: opted out.
Envelopes contain id, type, occurred_at, tenant identity and
data. Contacts and rendered message text are excluded. Handle optional additions and unknown
event types without rejecting the whole stream. Follow explicit major-version compatibility rules for
breaking changes.
Browser SSE and Web Push
Use fetch streaming on GET /v1/inbox/events with a browser grant in the header. Do not put
keys in an EventSource URL. changed carries a cursor; reset requires a fresh
snapshot. Use Last-Event-ID to resume. Stop on expiry/revocation, use bounded backoff after
transport loss and re-authorize before reconnecting.
Web Push payloads are generic. The browser service worker checks the active binding before displaying a notification. Server-to-server authority is checked again before delivery; enrollment is not permanent access to a resource. An accepted push is not proof of display.
Diagnosing a test
Keep message ID, sender operation ID, request ID and trace ID. Check the message timeline or operation status before retrying. The console shows safe response details but does not expose collector credentials, encryption keys or raw provider exceptions.
Open complete API reference