Ana MNotifications
Events and protocols

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-256 over raw body bytes.
  • Zavu: X-Zavu-Signature, timestamped v2 HMAC. Older/unrecognized formats are rejected.
  • Resend: svix-id, svix-timestamp and svix-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