Description

Purpose and use

Notifications deliver operational messages to users across in-app, email, SMS, and other configured channels. They keep customers and staff informed about account events, tasks, transfers, invoices, signatures, and service actions.

Who uses this. Customers, operations staff, support teams, compliance reviewers, and template administrators use notifications to receive, configure, or investigate event-driven messages.

How it works. A business event creates a notification with type, recipient, customer context, metadata, and delivery preferences. Templates and user preferences determine wording and channel delivery.

What users do. Users review notification lists, mark messages read, receive real-time updates, manage preferences, and troubleshoot missed or duplicate messages.

Outcomes and side effects. Notifications create communication history and can trigger unread counts or external delivery. They do not replace the authoritative audit trail for money movement or approval decisions.

Related manuals: Notification integration, Template admin, Users, Tasks.

Overview

The Notifications module provides a comprehensive real-time notification system for the CoreBanq platform. It supports multi-channel delivery, user preference management, and async processing through queue integration. The system enables real-time communication with users through various channels including email, SMS, and browser notifications.

Core Features

🔔 Real-Time Notifications

Server-Sent Events (SSE): Real-time browser notifications
WebSocket-like Experience: Persistent connections for instant delivery
Multi-User Support: Broadcast notifications to multiple users
Connection Management: Automatic client registration and cleanup

📡 Multi-Channel Delivery

System Notifications: In-app notifications via SSE
Email Integration: HTML/text email notifications
SMS Integration: Text message notifications
Extensible Architecture: Easy addition of new channels (WhatsApp, Telegram, etc.)

⚙️ User Preference Management

Granular Control: Per-user, per-customer notification preferences
Channel Selection: Users can choose which channels to receive notifications on
Event-Based Configuration: Enable/disable specific notification events
Group Management: Notifications organized by type (chat, task, etc.)

🔄 Queue-Based Processing

Async Processing: Non-blocking notification delivery
Message Queuing: Reliable delivery with queue persistence
Batch Processing: Efficient handling of multiple notifications
Error Recovery: Retry mechanisms for failed deliveries

🗃️ Complete State Management

Notification Storage: Persistent storage of all notifications
Read/Unread Tracking: Individual read state per user
Delivery Confirmation: Track delivery status across channels
Historical Data: Complete notification history and analytics

API Endpoints

Get User Notifications

GET /v1/notifications

Retrieve all notifications for the authenticated user.

Query Parameters

limit (optional): Maximum number of notifications to return (default: 50)
offset (optional): Number of notifications to skip (default: 0)
status (optional): Filter by read/unread status (read, unread, all)
customer_id (optional): UUID of a customer to filter notifications for a specific customer context. If omitted, notifications for all customers linked to the authenticated user are returned.

Response

Get Single Notification

GET /v1/notifications/{notification_id}

Retrieve a specific notification by ID.

Response

Mark Notification as Read

PATCH /v1/notifications/{notification_id}/read

Mark a specific notification as read using partial update. This endpoint accepts partial fields and can be used as a generic update endpoint for any notification fields.

Request Body (Optional)

{
  "read": true
}

Note: If no request body is provided, the notification will be marked as read by default.

Response

Delete Notification

DELETE /v1/notifications/{notification_id}

Delete a specific notification for the authenticated user.

Response

Get User Preferences

GET /v1/notifications/preferences

Get the current notification preferences for the authenticated user.

Response

Update User Preferences

PUT /v1/notifications/preferences

Update notification preferences for the authenticated user.

Request Body

Real-Time Connection (SSE)

GET /v1/notifications/sse

Establish a Server-Sent Events connection for real-time notifications.

Authentication: Bearer token required

Response Headers

The server sets the following on the stream:

Content-Type: text/event-stream
Cache-Control: no-cache, no-transform
Connection: keep-alive
X-Accel-Buffering: no — disables proxy buffering (nginx and similar) so frames are not held until the response ends

Connection Management

Persistent Connections: SSE connections remain open until the client disconnects or the server shuts down
Keep-Alive Heartbeat: The server sends a : keepalive comment frame every notifications.sse.heartbeat_seconds (default 25s) so intermediary proxies/gateways do not close the idle connection; a failed heartbeat write also surfaces dead peers for prompt cleanup. Keep this interval below any upstream proxy idle-read timeout.
No Server Timeout: WriteTimeout is unset for the server so long-lived streams are not cut off; the server's IdleTimeout applies only to idle keep-alive connections between requests, not to an active stream.
Automatic Cleanup: Server automatically cleans up disconnected clients
Multi-User Support: Each user can have multiple concurrent SSE connections
Cross-Origin Support: CORS headers are automatically set for browser compatibility

Event Stream Format

On connect the server emits an open frame, then a message frame per notification, and periodic keep-alive comments:

event: open
data: {"message": "Connection established"}

event: message
data: {"id":"123e4567-e89b-12d3-a456-426614174000","type":"chat","event":"message_received","title":"New Message","content":"Hello from John","link_url":"/chat/room/456","link_text":"View Message","read":false,"created_at":"2024-01-15T10:30:00Z"}

: keepalive

Connection Lifecycle

Connect: Client establishes SSE connection with authentication; server sends the open frame
Register: Server registers client for the authenticated user (missed system notifications are replayed)
Receive: Client receives real-time message frames as they occur, interleaved with : keepalive heartbeats
Disconnect: Client closes connection or navigates away
Cleanup: Server automatically removes client from active connections

Test Notification Endpoints

Trigger Test Notification (Queue-based)

POST /v1/notifications/trigger

Development/Testing Only - Trigger a test notification through the full notification system (queue-based processing).

Authentication: API Key required

Request Body

{
  "type": "chats",
  "event": "message_received",
  "title": "Test Notification",
  "content": "This is a test notification",
  "customer_id": "550e8400-e29b-41d4-a716-446655440000",
  "user_ids": ["123e4567-e89b-12d3-a456-426614174000"],
  "rec_type": "chats",
  "rec_id": "789e4567-e89b-12d3-a456-426614174000"
}

Response

{
  "message": "Notification sent to all connected users"
}

Send Direct SSE Notification

POST /v1/notifications/sse

Development/Testing Only - Send a notification directly to SSE clients (bypasses queue processing).

Authentication: API Key required

Request Body

Same as trigger endpoint above.

Response

{
  "message": "Notification sent to all connected users"
}

Error Codes

Code	Description
notifications_m.invalid_user_id	Invalid or missing authenticated user ID
notifications_m.invalid_id	Invalid notification ID
notifications_m.not_found	Notification not found
notifications_m.failed_to_mark_as_read	Failed to mark notification as read
notifications_m.failed_to_delete	Failed to delete notification
notifications_m.invalid_group	Invalid notification group
notifications_m.invalid_channel	Invalid notification channel
notifications_m.invalid_event	Invalid notification event
notifications_m.failed_to_fetch_notifications	Failed to fetch notifications
notifications_m.failed_to_fetch_preferences	Failed to fetch notification preferences
notifications_m.failed_to_update_preferences	Failed to update notification preferences

Best Practices

Performance Guidelines

Connection Limits: Implement per-user SSE connection limits
Message Batching: Process notifications in batches for efficiency
Queue Management: Monitor queue depths and processing rates
Database Optimization: Use appropriate indexes for notification queries

Security Guidelines

Authentication: Always verify user identity for notification access
Data Sanitization: Sanitize notification content before delivery
Audit Logging: Log all notification operations for security auditing
Rate Limiting: Implement rate limits for notification creation

User Experience Guidelines

Graceful Degradation: Handle SSE connection failures gracefully
Progressive Enhancement: Provide fallback for users without SSE support
Clear Messaging: Use clear, actionable notification content
Preference Respect: Always honor user notification preferences

Dependencies

Required Services

Database: PostgreSQL for notification storage
Queue: Message queue system (local or AWS SQS)
Storage: CoreBanq storage abstraction
RBAC: Role-based access control system

External Integrations

Email Service: For email notifications
SMS Service: For text message notifications
Authentication: User authentication and authorization

Configuration Dependencies

notifications.yaml: Notification configuration
queue.yaml: Queue system configuration
Database migration scripts for notification tables

The Notifications module provides a robust, scalable foundation for real-time user communication in the CoreBanq platform, with comprehensive features for multi-channel delivery, user preference management, and reliable message processing.

On this page