> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Notifications hub

> A map of the notifications section — the tenant-scoped inbox for platform events, the kinds and categories it carries, how to browse, filter, mute, and dismiss rows, and how delivery fans out across the bell, email digests, push, and webhooks.

# Notifications hub

The **Notifications** hub is the bell in the top bar and the page behind it (`/notifications`). It is your org's tenant-scoped inbox for platform events: delivery alerts, spend-cap and wallet warnings, compliance flags, AI agent escalations, security alerts, and system announcements. It is deliberately separate from the other two inbox-like surfaces: **Inbox** holds customer conversations, and **Team Chat** holds operator chatter. Anything the platform itself needs to tell you lands in Notifications.

This page is an orientation map, not a walkthrough. Each section links the deeper page that owns the steps.

## The surfaces at a glance

| Surface | Where | What it answers |
| - | - | - |
| **Notifications page** | `/notifications`, behind the bell | The live feed of your org's platform events, filterable by kind and severity. See [Read and filter the notifications feed](/guides/notifications-feed). |
| **Notification preferences** | **Settings → Notifications** | Your personal per-category channel matrix (email, push, webhook) and frequency. See [Configure notification channels](/guides/notifications-settings). |
| **Email digest** | **Settings → Notifications → Digest** | The org-level daily or weekly aggregate email, owned by owner/admin. See [Notification digest vs. per-user preferences](/guides/digest-and-notification-channels-faq). |
| **Webhook fan-out** | **Developer → Webhooks** | Org-level server-to-server event delivery to your endpoint, independent of any member's preferences. See [Webhook events](/webhooks/events). |
| **Notifications API** | `GET /api/v1/notifications`, `.../stream` | Programmatic list, unread count, mark-read, dismiss, and the live SSE stream. See [Notifications API](/api-reference/notifications). |

## Notification taxonomy

Notifications are emitted by every pillar of the platform: SMS, WhatsApp, email, voice, verify, AI agents, and billing. Each notification carries a **kind** — the closed enum of concrete events, such as `credit_low`, `agent_handoff_pending`, or `new_signin_from_new_device` — grouped into a **category** that your preferences key on: `billing`, `security`, `messaging`, `campaigns`, `agents`, and `system`. Kinds fall into three families:

* **Alerts** — something needs your action now: a wallet that hit zero and paused outbound, a campaign that finished with errors, an AI agent escalation waiting for a human, a conversation that breached its SLA.
* **Anomalies** — something deviated from baseline: unusual billing activity, an email DNS regression that puts deliverability at risk, a webhook endpoint auto-disabled after repeated failures.
* **System notes** — lifecycle records: number orders completing, regulatory bundles approved or declined, port status changes, teammate role changes, API key creates and revokes.

Every kind renders with a category icon and a severity — `info`, `warning`, or `error` — and the feed's kind filter mirrors the same enum, so a kind can never be invisible to filtering. The full kind-to-icon table lives in [Read and filter the notifications feed](/guides/notifications-feed).

For how a single event fans out to the bell, an immediate email, or a scheduled digest, see [The notification model](/concepts/notification-model). For which control owns which outlet — per-user preference vs org digest vs org webhook sink — see [Notification digest vs. per-user preferences](/guides/digest-and-notification-channels-faq).

## Browsing, filtering, muting, and archiving

* **Browse** — the feed is a virtualised, cursor-paginated list; a **Load more** control pages history in, and only the visible window of rows mounts no matter how deep you scroll. Above the feed, **Active platform alerts** pin persistent issue states — outbound paused, KYC pending, compliance risk, webhook backlog, number document expiry — so the center is never empty while a real issue is outstanding.
* **Filter** — three filters combine freely: **Unread only**, **Kind** (the full enum, group-ordered the way you think about it), and **Severity**. A malformed filter value never errors the page; it is ignored and the feed loads unfiltered.
* **Mute** — muting is per category, on **Settings → Notifications**: switch a category's channel off for yourself, or drop its frequency to `daily` or `weekly`. Security kinds bypass every mute — sign-ins from new devices, 2FA changes, password or email changes, and API key events always mint a row and deliver, so a hijacked session cannot silence the takeover signal.
* **Archive** — there is no separate archive shelf; dismissal and expiry are the archive. **Dismiss** a user-scoped row from its hover control (a \~5 second undo window catches mistakes) and it leaves your feed; org-wide rows show no dismiss control and expire on their own clock. Rows whose expiry has passed drop out of every list and unread count; rows without one persist until dismissed.
* **Read state** — opening a row marks it read, hover reveals the read check, and **Mark all read** clears the badge in one click. Read state stays in sync across open browser tabs.

### Real-time push with a poll safety net

The page subscribes to the live stream (`GET /api/v1/notifications/stream`, server-sent events), so a new row lands without a refresh. A **30-second poll** sits behind it: if a stream frame is missed — a laptop resuming from sleep between heartbeats, a dropped connection — the poll self-corrects. A feed that looks up to \~30 seconds stale is the fallback working, not a bug, and the bell badge polls on the same cadence so it never sticks on a stale number. The stream caps at 50 concurrent connections per tenant, enforced cluster-wide, and requires a browser user-agent and a trusted origin. The mechanics and a freshness decision table live in [Configure notification channels](/guides/notifications-settings).

## Per-channel delivery settings

Each member of the org tunes their own matrix on **Settings → Notifications**: three channel toggles per category — email, push, and webhook — plus a frequency (`immediate` by default, `daily`, or `weekly`). Defaults are on until you change them; `security` is exempt and always on. The three destinations come from the notification model's fan-out ([The notification model](/concepts/notification-model)); here is where each one is tuned:

* **In-app** — the bell and the feed receive every row your preferences do not mute, and every security row regardless. This is the only surface that always has the full picture.
* **Email** — immediate per event by default, or rolled into the org digest: an owner/admin opt-in on **Settings → Notifications → Digest** with a `daily` or `weekly` cadence and an optional category list (an empty list means all six categories). Worked example: setting the `campaigns` frequency to `daily` turns N campaign emails into one aggregated digest email.
* **Push** — per-user push subscriptions follow the same category matrix; they are personal and distinct from org-level sinks.
* **Webhook** — the per-user webhook toggle delivers your categories to your endpoint; **Developer → Webhooks** is the org-level sink that fans developer events out regardless of any member's opt-out. Teams commonly terminate either at a Slack incoming webhook or an ops bot, which is the Slack fan-out path. Signing and payload contract: [Webhook events](/webhooks/events).

The per-category matrix, the digest API (`GET`/`PUT /api/v1/notifications/digest/settings`, `PUT` restricted to owner and admin), and the always-on security list are documented with worked samples in [Configure notification channels](/guides/notifications-settings).

## Sub-account notification recipients

If you operate sub-accounts, rate-sheet emails and account-balance alerts can route to a per-sub-account recipient list instead of the org default, with inheritance up the reseller chain and a safe fallback when nothing is configured. See [Sub-account notification recipients](/guides/subaccounts-notification-recipients).

## Where to go next

* [The notification model](/concepts/notification-model) — event fan-out, categories, channels, and digests.
* [Triage the Notification Center](/guides/in-dashboard-notifications) — what raises a notification and how to work it day to day.
* [Read and filter the notifications feed](/guides/notifications-feed) — the kind taxonomy, icons, filters, and read state.
* [Configure notification channels](/guides/notifications-settings) — per-user toggles, the digest API, and freshness debugging.
* [Notification digest vs. per-user preferences](/guides/digest-and-notification-channels-faq) — what each control owns and which alerts ignore your mutes.
* [Sub-account notification recipients](/guides/subaccounts-notification-recipients) — per-sub-account routing for rate-sheet and balance alerts.
* [Notifications API](/api-reference/notifications) — list, unread count, mark-read, dismiss, and the SSE stream.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.