Skip to main content

​
The notification model

When something happens in your workspace — a campaign finishes, a payment fails, a new sign-in arrives, a template is rejected — Orbit turns it into a notification and fans it out to the people who need to act on it. This page explains that model end to end: which destinations a notification can reach, how event kinds map to categories you can tune, the per-user live channel behind the bell, and how the digest scheduler turns a noisy stream into a scheduled summary. The guide at Triage the Notification Center walks through the dashboard surface; this page is the model behind it.

​
Section 1 — The three destinations a notification can reach

Every notification Orbit emits can reach up to three destinations. Only one of them is authoritative.
  • The bell row (authoritative). A persistent row in the Notification Center (the page behind the bell icon at /notifications). This row is the source of truth: it is what the unread badge counts, it is what the list page shows, and it survives until you dismiss it or it expires. Channel preferences gate outbound fan-out, but the persisted row in the Notification Center is the record every other surface reads from.
  • An immediate email. For event classes that aren’t security-critical or in-app-only, a per-event email fires when your category preference has email enabled and your frequency for that category is immediate (the default).
  • A scheduled digest email. When you set the frequency for a category to daily or weekly, the per-event email is replaced by an entry in the digest queue; a background scheduler bundles pending entries into a single email at the cadence you picked.
Three kinds of events bend those rules deliberately:
  • Security-critical classes (new device or new IP sign-in, password change, 2FA changes, API key creation or revocation, member role changes, fraud and billing anomalies) bypass per-user outbound preferences entirely. A hijacked session could otherwise mute the takeover signal before the legitimate user sees it. The dedicated security dispatch path owns their email so the generic fan-out doesn’t double-send.
  • In-app-only classes (team-chat pings, webhook endpoint auto-disabled) mint the bell row but never leave the app. The bell is their only surface, so it is minted unconditionally instead of reading the outbound channel toggles.
  • Always-bell classes (an email DNS health regression detected interactively on the deliverability page) mint the bell unconditionally — the daily deliverability cron writes its own bell row the same way — while their email stays gated by the normal email toggle, so the interactive page and the cron never disagree on whether the row exists.
Think of outbound channels as extra reach, not the registry. The registry is the bell row; email and digest are projections of it gated by your preferences.

​
Section 2 — Categories and the event-kind map

Each event kind (a closed enum across the platform — a campaign completion, a payment failure, a sign-in from a new device, a template approval, and the rest) maps to exactly one category. Your Settings → Notifications page shows one card per category with its own email / push / webhook toggles and its own frequency picker. The categories, with examples of the kinds that land in each: A kind that has no explicit mapping falls back to system — the broadest default-on bucket — so a forgotten mapping never silently routes an event into a category you disabled. The category assignment is what makes the Settings → Notifications toggles meaningful: unticking “Messaging → Email” suppresses exactly the kinds listed under that row and nothing else. The same category vocabulary carries into the digest scheduler (below).

​
Section 3 — The per-user live channel

The bell’s live view rides a server-sent events channel scoped to a single user (notifications:user:<userId> on the wire). When a notification row is minted for you, the fan-out publishes the row onto your own channel, so the badge and dropdown update without polling and without broadcasting your teammates’ rows to every open tab in the org. If you are offline when the event fires, nothing is lost: the row persists and the badge catches up on the next list fetch. A Redis hiccup during the publish is degradable the same way — the row is already written, the push is best-effort, and the initial GET on your next sign-in reconciles. Channel scoping is per-user, not per-org, because one tenant with hundreds of operators should not page every browser on every event.

​
Section 4 — The digest model

The digest is an org-level decision with per-recipient opt-in. Four pieces cooperate:
  1. Org master toggle, frequency, and category filter. The org holds one settings row: on/off, a default frequency (daily or weekly), and a category filter (empty filter = all categories). Until an admin enables the digest for the org, per-user daily/weekly choices queue rows but send nothing — flipping the toggle drains the backlog on the next tick.
  2. Per-(org, user) recipient registry. Each member has an opted_in flag. Until anyone touches it, the UI synthesizes a default registry in which admins are opted in; the first explicit toggle writes the real row. Opted-in recipients are the ones a digest email is actually addressed to.
  3. The per-user frequency field. On Settings → Notifications each user sets a per-category frequency. immediate (the default) fires the per-event email path; daily or weekly enqueues the event into the digest queue instead. The bell row is written in all cases — frequency only gates the outbound email.
  4. The scheduler. On a ten-minute cadence it sweeps the due rows of the digest queue (locked reads so concurrently running workers can’t double-send), groups them per user, and sends one email grouping every pending entry for the window. A successful send stamps the rows sent; a failure leaves them for the next tick. An org with nothing pending — or a digest composition that comes back empty — is skipped rather than emailed an empty summary. The window-to-window overlap guard uses the org’s last-digest timestamp.
You can compose the would-be next digest on demand with the admin-only preview endpoint (POST /api/v1/notifications/digest/preview, optionally with a bounded lookback override) — the call Settings → Notifications → Digest makes when it renders its live preview card. Composition reads the tenant’s own ledger, inbox, and notification tables, so the preview reflects real data.

​
Section 5 — Billing and channel-quality alerts in the same model

Low-balance and channel-quality events are notifications before they are anything else, and they reuse the same pipeline:
  • Billing. payment_failed, top_up_succeeded, credit_low, wallet_emptied, number_renewal_failed, and unusual_billing_activity all map to the billing category, so one toggle shapes all of them. The pipeline that debits your wallet is described in How billing meters your usage; the kinds above are the alert surface on top of that pipeline.
  • Channel quality. WhatsApp template approvals or rejections (whatsapp_template_status_changed), sender-ID review outcomes, port-in status changes, and deliverability alert rule firings route through messaging; SLA or KPI rule firings route through agents. Filtering by category on the Notification Center page separates “money events” from “channel events” without remembering individual kind names.
In both cases the model holds: a row lands in the Notification Center, the category routes the outbound, and a subscribed digest summarizes it at your chosen cadence.

​
A worked example: tracing whatsapp template auto-paused

Suppose Meta scores your holiday_promo template RED and the template has auto-pause enabled. Orbit pauses it before Meta penalizes the account, and the event flows end to end:
  1. Event minted. The event kind is whatsapp_template_status_changed-class WhatsApp quality signal; it maps to the messaging category with a per-event severity.
  2. Recipients resolved. The fan-out looks up the org’s admin and owner set (the people who manage messaging channels).
  3. Bell row minted. A row lands in the Notification Center titled “WhatsApp template paused” with the template name and an action link to the templates page. This row exists regardless of outbound choices.
  4. Live badge. Your per-user channel pushes the row, so the bell badge increments while the dashboard is open.
  5. Outbound gated by your preference. If your messaging → email toggle is on with frequency immediate, a per-event email goes out now. If you set messaging frequency to daily, the event enters the digest queue instead and arrives in tomorrow’s single digest email. If the org digest toggle is off, that queue entry sits unsent.
  6. Digest composition. When the scheduler ticks with the org enabled and you opted in, the event appears as a highlight (title, summary, action link) inside the one email you get for that window — together with every other messaging entry that accumulated.
Every step honors the same model; nothing about “WhatsApp” is special-cased outside the category map.

​
Where this fits

Non-goals of this page: webhook subscriptions (a separate developer family), and marketing push (also separate — the channels named here, email / push / webhook, are the operator-alert preference buckets).