Triage the Notification Center

The Notification Center is the dashboard’s persistent alert feed — the full list behind the bell icon. Where the bell dropdown gives you a quick glance at what’s new, this page is where you triage, batch-mark-read, and review history. Its own subtitle says what it holds: persistent platform alerts that need your attention. Open it from /notifications (bell icon, top right).

What a notification is

A notification is a durable, row-scoped platform event that surfaced somewhere in your org and needs a human view. It carries:

a title + body — what happened, in plain terms
a kind — which event class it belongs to (campaign, payment, security, inbox, …)
a severity — info, warning, or error
an optional action URL — a deep link to the surface that resolves it
a read/unread state and an optional expiry

Below the persistent row feed, the page also pins Active platform alerts — a cross-module snapshot of issue states still resolving (outbound paused, KYC pending, compliance risk, webhook backlog, number document expiry) — so the center is never empty while a real issue is outstanding.

What raises a notification

Notification kinds are a closed enum on the API, and the dashboard’s filter dropdown mirrors that enum. The major groupings: Platform alerts

campaign_completed / campaign_failed — a campaign finished (or finished with errors)
payment_failed / top_up_succeeded / credit_low / wallet_emptied / number_renewal_failed / unusual_billing_activity — billing state changes. A number_renewal_failed row means a held number’s renewal charge hit an empty wallet; the recovery path (top up, auto-release, reclaim) is in the INSUFFICIENT_BALANCE troubleshooting tree.
dlq_alert / webhook_endpoint_disabled / webhook_endpoint_decryption_failed — integration failures
port_status_changed / telnyx_* (regulatory, number order, port request) / number_compliance_requested — number lifecycle
kyc_decision / sender_id_review / compliance_incident — compliance decisions
account_fraud_alert — account-level fraud / traffic anomaly
email_dns_regression — deliverability regression
system_alert — generic platform alert

Security alerts

new_signin_from_new_ip / new_signin_from_new_device / password_changed / email_changed / recovery_email_changed
two_factor_disabled / two_factor_method_removed / mfa_backup_codes_regenerated
api_key_created / api_key_revoked
org_member_role_changed / org_member_removed

Security kinds are always shown regardless of your notification preferences — suppressible preferences would let a hijacked session mute the takeover signal.

Agent + inbox alerts

agent_handoff_pending — AI agent escalated to a human
agent_kpi_alert_fired / voice_queue_sla_warning / voice_queue_alert_rule_fired / messaging_deliverability_alert_fired / acd_disposition_required — operational thresholds breached
inbox_new_message / inbox_conversation_assigned / inbox_new_conversation / inbox_mention / inbox_sla_breach / inbox_follower_update / inbox_ticket_follower_update / team_chat_message / csat_low / whatsapp_template_status_changed — inbox + messaging state changes

Delivery channels

Every notification lands in-app — the bell row, the live stream, and the Notification Center list. Outbound delivery is layered on top:

In-app — persisted row + live SSE feed. This is the only delivery for a few high-frequency, low-stakes kinds (for example team_chat_message), where per-event email would be spam.
Email digest — for outbound-eligible kinds, a per-user digest (daily or weekly) rolls up unread notifications in opted-in categories: billing, security, messaging, campaigns, agents, system. Configure it under Settings → notification digest, or via the API below.
Category-level preferences — you can mute a whole category for outbound delivery per user (Settings → notifications). Muted categories still mint the in-app bell row; security-critical kinds ignore the mute entirely.

Digest API

Admins manage the digest from the API; member opt-ins are per user. Read the org’s settings:

curl https://api.orbit.devotel.io/api/v1/notifications/digest/settings \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": {
    "organization_id": "org_abc123",
    "enabled": true,
    "frequency": "daily",
    "categories": ["billing", "security"],
    "last_digest_at": null,
    "created_at": "2026-08-01T09:04:11.203Z",
    "updated_at": "2026-08-12T14:22:48.901Z"
  }
}

Update the settings (owner/admin only): PUT /api/v1/notifications/digest/settings accepts enabled (boolean), frequency ("daily" or "weekly"), and categories (an array of billing, security, messaging, campaigns, agents, system). An empty categories array means every category is emailed. List recipients:

curl https://api.orbit.devotel.io/api/v1/notifications/digest/recipients \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": [
    {
      "id": "ndr_7f1a…",
      "organization_id": "org_abc123",
      "user_id": "usr_4e2c…",
      "email": "adana@studio.com",
      "name": "Adana Notay",
      "role": "admin",
      "opted_in": true,
      "created_at": "2026-08-01T09:04:11.203Z",
      "updated_at": "2026-08-01T09:04:11.203Z"
    }
  ]
}

Toggle a member’s opt-in (owner/admin only):

curl -X PATCH https://api.orbit.devotel.io/api/v1/notifications/digest/recipients/usr_4e2c… \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"opted_in": false}'

Admins can also dry-run the next digest with POST /api/v1/notifications/digest/preview (?hours= bounds the lookback window, max 168).

Read, dismiss, retention

Read/unread — a PUT /notifications/:id/read call marks a single row read; POST /notifications/read-all clears the badge. The dashboard streams delivery so read state syncs across open browser tabs.
Dismiss — user-scoped notifications can be dismissed; the row hides immediately and the delete commits after a short undo window (~5s in the UI).
Retention — rows carrying an expires_at timestamp are automatically filtered out of every list and unread-count response after that moment passes, so a stale “campaign completed” never lingers past its useful life. Rows without an expiry persist until you dismiss them.

API walkthrough: list, badge, mark-read, dismiss

All responses share the standard envelope: data plus a meta block with request_id and timestamp. Check the badge:

curl https://api.orbit.devotel.io/api/v1/notifications/unread-count \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": { "count": 3 },
  "meta": { "request_id": "req_01J…", "timestamp": "2026-08-27T18:33:17Z" }
}

List the unread rows:

curl "https://api.orbit.devotel.io/api/v1/notifications?unread_only=true&limit=10" \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": {
    "data": [
      {
        "id": "notif_4f8c1d2a3b4e5f60718293a4b5c6d7e8",
        "user_id": "usr_9f3a…",
        "org_id": "org_abc123",
        "kind": "new_signin_from_new_device",
        "severity": "warning",
        "title": "New sign-in from an unrecognized device",
        "body": "Chrome on macOS — first seen 2 minutes ago.",
        "action_url": "/settings/security",
        "read_at": null,
        "created_at": "2026-08-27T18:12:04.551Z",
        "expires_at": null,
        "source_pillar": "auth",
        "category": "security"
      }
    ],
    "pagination": { "cursor": null, "has_more": false }
  },
  "meta": { "request_id": "req_01K…", "timestamp": "2026-08-27T18:33:18Z" }
}

Each row carries id, user_id, org_id, kind, severity, title, body, action_url, read_at, created_at, expires_at, source_pillar, and category — no other fields. Filters on GET /notifications: unread_only, kind, severity, source_pillar (alias pillar), category, cursor, limit. GET /notifications/global adds since / until ISO timestamps for time-boxed feeds.

A malformed filter on a list read never returns 422: the API ignores it and loads the list unfiltered, so a stale bundle or an off-range limit still renders the feed.

Mark one row read, then clear the rest:

curl -X POST \
  https://api.orbit.devotel.io/api/v1/notifications/notif_4f8c1d2a3b4e5f60718293a4b5c6d7e8/read \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": {
    "id": "notif_4f8c1d2a3b4e5f60718293a4b5c6d7e8",
    "user_id": "usr_9f3a…",
    "org_id": "org_abc123",
    "kind": "new_signin_from_new_device",
    "severity": "warning",
    "title": "New sign-in from an unrecognized device",
    "body": "Chrome on macOS — first seen 2 minutes ago.",
    "action_url": "/settings/security",
    "read_at": "2026-08-27T18:34:02.119Z",
    "created_at": "2026-08-27T18:12:04.551Z",
    "expires_at": null,
    "source_pillar": "auth",
    "category": "security"
  },
  "meta": { "request_id": "req_01L…", "timestamp": "2026-08-27T18:34:02Z" }
}

curl -X POST https://api.orbit.devotel.io/api/v1/notifications/read-all \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": { "affected": 2 },
  "meta": { "request_id": "req_01M…", "timestamp": "2026-08-27T18:34:10Z" }
}

Dismiss a row:

curl -X DELETE \
  https://api.orbit.devotel.io/api/v1/notifications/notif_8c2e9d… \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": { "deleted": "notif_8c2e9d…" },
  "meta": { "request_id": "req_01N…", "timestamp": "2026-08-27T18:35:01Z" }
}

Dismiss takes a 404 when the row is org-wide (not user-scoped) — those rows expire on their own clock instead.

Live tail over SSE

GET /notifications/stream is a text/event-stream endpoint for your own queueing worker, not just the dashboard. Browsers authenticate it with a short-lived one-time token because EventSource cannot set headers:

POST /notifications/sse-token → { "data": { "ot": "sset_…", "expires_in": 90 } }
Pass ?ot=<token> (preferred) or ?token=<JWT|API-key> as a query param on the stream URL. A dv_-prefixed token is treated as an API key; anything else as a bearer token.

A Node consumer loop with plain fetch (also the pattern the @devotel/sdk-node client wraps; the SDK’s notifications.list / markRead / markAllRead / archive methods back the same routes):

import { request } from "undici";

const API = "https://api.orbit.devotel.io";
const HEADERS = { "X-API-Key": process.env.ORBIT_API_KEY };

// Mint a one-time SSE token (90s ttl).
const { data } = (await request(`${API}/api/v1/notifications/sse-token`, {
  method: "POST",
  headers: HEADERS,
})).body.json();

const res = await request(
  `${API}/api/v1/notifications/stream?ot=${data.ot ?? ""}`,
  { headers: HEADERS },
);
for await (const chunk of res.body) {
  for (const raw of chunk.toString().split("\n\n")) {
    if (!raw.trim() || raw.startsWith(":")) continue; // heartbeats / comments
    // Frames look like `event: notification.created\ndata: {...}`
    const event = raw.match(/^event: (.+)$/m)?.[1];
    const payload = raw.match(/^data: (.+)$/m)?.[1];
    if (event && payload) {
      const notif = JSON.parse(payload);
      console.log(event, notif.kind, notif.title, notif.action_url);
    }
  }
}

The stream emits :heartbeat comments plus an optional connected frame ({agent.client} is the only event type you’ll usually need the envelope for). The dashboard-facing freshness model — how that stream and a 30-second poll safety net converge — is covered in Configure notification channels. Connection budget: 50 per tenant, enforced cluster-wide; a browser UA + trusted Origin header is required. Sample framed payload on the stream:

event: notification.created
data: {"id":"notif_4f8c…","user_id":"usr_9f3a…","org_id":"org_abc123","kind":"dlq_alert","severity":"error","title":"Webhook deliveries backing up","body":"3,412 events in the dead-letter queue on https://api.acme.com/hooks","action_url":"/developer/webhooks","read_at":null,"created_at":"2026-08-27T18:41:33.400Z","expires_at":null,"source_pillar":"developer","category":"messaging"}

Security-row shape

Security-critical events (account takeover, 2FA disabled, password/email change, API-key mint/revoke, role change, billing anomaly, decryption-failure, fraud alert) always mint a row and always bypass user preference muting — a hijacked session can’t silence them:

{
  "id": "notif_aa1b…",
  "kind": "api_key_created",
  "severity": "info",
  "title": "API key created",
  "body": "prod-ingest-01 (full access)",
  "action_url": "/settings/api-keys",
  "read_at": null,
  "created_at": "2026-08-27T18:44:52.991Z",
  "expires_at": null,
  "category": "security"
}

Notifications vs webhooks

Notifications are for a human operator; webhooks are for your code.

A notification is a durable UI row an operator triages from the dashboard. Read, dismiss, filter — no endpoints to expose.
A webhook is a server-to-server POST to an endpoint you control. You subscribe to webhook events and process them automatically.

The two overlap intentionally: developer-facing failure modes (delivery stuck in the dead-letter queue, an endpoint auto-disabled, decryption failing) also mint an in-app notification so an operator sees it — even when your webhook handler isn’t watching. For the full event catalog, see Webhook Events.

Operator runbook tips

The notification center and on-call alerting serve different altitude:

Notification Center = state an entire org sees; any member with dashboard access can triage it.
On-Call alerting = an engineering-to-action escalation loop (rotation → escalation policy → page via Messages) for time-critical issues.

Compose the two deliberately:

A dashboard notification lands (e.g. dlq_alert, wallet_emptied, webhook_endpoint_disabled).
Your on-call rotation consumes that queue if it needs a human now — page the current on-call via On-Call, with dashboard access to review the row before acting.
If the alert is genuinely routine, the center’s filters + category digests keep on-call pages from flooding the rotation with noise.

For operator-facing runbooks: subscribe a category digest to the rotation’s on-call email for low-severity alerts, and reserve On-Call paging for security-critical, wallet-pausing, and integration-failure kinds.

WhatsApp

Developer console

Guides

Messaging Controls

Audience & Support Tools

Triage the Notification Center

Triage the Notification Center

What a notification is

What raises a notification

Delivery channels

Digest API

Read, dismiss, retention

API walkthrough: list, badge, mark-read, dismiss

Live tail over SSE

Security-row shape

Notifications vs webhooks

Operator runbook tips

​Triage the Notification Center

​What a notification is

​What raises a notification

​Delivery channels

​Digest API

​Read, dismiss, retention

​API walkthrough: list, badge, mark-read, dismiss

​Live tail over SSE

​Security-row shape

​Notifications vs webhooks

​Operator runbook tips

Triage the Notification Center

What a notification is

What raises a notification

Delivery channels

Digest API

Read, dismiss, retention

API walkthrough: list, badge, mark-read, dismiss

Live tail over SSE

Security-row shape

Notifications vs webhooks

Operator runbook tips