Notifications Admin

This document describes the Notifications admin page at /admin/notifications in the Atlas Guard Admin UI and the notification service endpoints it relies on.

---

Access & Navigation

• Sidebar link: System Management → Notifications → /admin/notifications

• Permissions: requires Org Admin access (UI-gated).

• Top header bell icon: currently a visual placeholder only (no click behavior).

---

UI Features (current behavior)

Across tables in this page:

• Sorting: click any sortable table header to toggle ascending/descending.

• Pagination: each table supports local pagination (page + rows-per-page).

• Row details: some tables may show truncated values in the table; details should be available via a details view/modal where implemented.

Tabs

1) Failed Notifications (Analytics tab)

• Fetches failed notification records and displays:

  • Notification ID, Event Type, Channel, User ID, Failed At, Error Message

• Supports Retry action per record.

2) Delivery Logs (Logs tab)

• Fetches recent delivery attempts and displays:

  • Timestamp, Notification ID, Provider, Status, Duration, Response

• Filters

  • Server-side (sent as query params): provider, status, hours, limit

  • Client-side: duration range (minDurationMs, maxDurationMs)

3) Event Types (Admin tab)

• Lists event types for dropdowns/publishing and management.

4) Subscriptions (Subscriptions tab)

• Lists subscriptions with a UI filter:

  • Active only vs All

• Uses the same endpoint with/without active_only=true.

---

Routing / Proxy Configuration (Atlas Guard)

The Admin UI calls the notification service via the Atlas Guard proxy:

/v1/notification_service/<path>

This requires a service_routes entry:

• service_name: notification_service

• url: notification service base URL

• api_path: typically /api/v1 (so /v1/notification_service/admin/notifications forwards to <url>/api/v1/admin/notifications)

See Service Routes for details on api_path and path transformation.

---

Required Notification Service Endpoints (canonical)

Health

• GET /api/v1/health

• GET /api/v1/health/detailed

Notifications (admin)

List notifications

GET /api/v1/admin/notifications/

Query params (recommended):

• status (e.g. failed)

• delivery_channel

• skip

• limit

• (optional) event_type, user_id

Response (recommended):

{
  "notifications": [],
  "pagination": { "total": 0, "skip": 0, "limit": 100, "has_more": false },
  "total_count": 0
}

Each notification should include (minimum for UI):

• id, user_id, event_type, delivery_channel, status

• created_at (or failed_at if the table intends to show failure time)

• error_message for failures

Retry notification

POST /api/v1/admin/notifications/{notification_id}/retry

Body:

{ "max_attempts": 3, "delay_seconds": 30 }

Delivery Logs

Recent delivery logs

GET /api/v1/admin/notifications/delivery-logs/recent

Query params:

• hours (default 24)

• limit (default 100)

• status (optional)

• provider (optional)

Response (recommended):

{ "logs": [] }

Each log should include (minimum for UI):

• id, notification_id, provider, status

• duration_ms

• created_at (RFC3339 with timezone)

• response_message (or error details)

Event Types

• GET /api/v1/admin/event-types/ (+ optional filters like active_only, category)

• POST /api/v1/admin/event-types/

• PUT /api/v1/admin/event-types/{id}

• DELETE /api/v1/admin/event-types/{id}

• GET /api/v1/admin/event-types/categories/list

Subscriptions

• GET /api/v1/admin/subscriptions/ (supports active_only, delivery_channel, event_type)

• PUT /api/v1/admin/subscriptions/{id}

• DELETE /api/v1/admin/subscriptions/{id}

• GET /api/v1/admin/subscriptions/stats/summary

---

Timestamp Format Recommendation

Use RFC3339 with timezone and milliseconds, e.g.:

• ✅ 2026-01-07T11:16:25.600Z

• ❌ 2026-01-07T11:16:25.600469 (microseconds, no timezone)