Notifications
The notification system sends alerts to users across several channels when relevant platform events happen.
Supported channels
| Channel | How it reaches the user |
|---|---|
| In-app | Appears in the application panel |
| Sent to the user's address asynchronously | |
| Webhook | A POST to a URL configured by the tenant |
| Web push | Browser Notification API (a registered Web Push subscription) |
| Native push | iOS / Android through a device token (FCM) |
Each channel can be turned on or off per user and notification type.
Notification types
| Type | When it fires |
|---|---|
USER_CREATED | When a new account is created |
USER_INVITED | When an invitation to a company arrives |
USER_INVITATION_ACCEPTED | When an invitation is accepted |
ROLE_CHANGED | When a user's role changes |
EXPORT_READY | When an export completes |
PAYMENT_FAILED | When a subscription charge fails |
SUBSCRIPTION_CHANGED | When a subscription is cancelled or modified |
INVOICE_AVAILABLE | When a new invoice is generated |
TRIAL_ENDING | When the trial period is about to expire |
FEEDBACK_RECEIVED | When new feedback arrives from the beta tester widget — every platform super administrator is notified in-app |
CUSTOM | Free content composed through POST /notifications/send. It is not a typed catalogue type in the API. |
API — Composed send
OWNER/ADMIN (JWT + active company) or the tenant's secret key (sk_ with the OWNER/ADMIN role) can send immediate notifications.
POST /notifications/send
Authorization: Bearer <token> # or X-API-Key: sk_…
X-Company-Id: <companyId>
Content-Type: application/jsonRecipient modes
mode | Behaviour |
|---|---|
broadcast | Every current member of the company |
users | Closed list in userIds (mandatory, non-empty). Invalid or other-tenant ids are skipped without reporting failures |
Content (mutually exclusive):
- Free:
{ "title", "body", "destination?" }— limits: title 255, body 10000, destination 2048. Omittingdestinationis valid; when included it must be a non-empty internal route starting with/.null, empty,javascript:/http(s)://schemes and protocol-relative//URLs → 400. - Template:
{ "type", "payload" }— catalogue types (notCUSTOM). The API requirespayloadto include everyrequiredFieldsof the template; missing or blank keys → 400.
Channels (optional):
channels: list ofin_app|email|webhook|web_push|native_push- Omitted or
[]→ default["in_app"] - Delivery = intersection with the recipient's preferences / devices / webhook
- Native push with no app client linked to the company → skipped and reported in
omissions(no_app_client_linked) - App linked but no recipient with a native device →
omissionswithno_recipient_devices
Response: 202 Accepted with:
{
"accepted": true,
"channels": ["in_app"],
"omissions": []
}No per-recipient delivery state (send-and-forget). MEMBER → 403.
Free broadcast example:
{
"mode": "broadcast",
"title": "Company notice",
"body": "All-hands tomorrow",
"destination": "/announcements"
}Multi-channel example:
{
"mode": "users",
"userIds": ["member-uuid"],
"title": "Ping",
"body": "Hello",
"channels": ["in_app", "email", "native_push"]
}List plus template example:
{
"mode": "users",
"userIds": ["member-uuid"],
"type": "EXPORT_READY",
"payload": {}
}Delivery reuses NotificationsService.notify() restricted to the chosen channels (preferences + templates). IN_APP with a live channel applies SSE. With no registered push device, that channel is skipped without failing the send.
Every immediate send also leaves a row in the outbox (notification_composed_sends, status executed) with the requested channels.
API — Push devices
Any authenticated user can register and unregister push endpoints bound to their account (and active company).
POST /notifications/devices
Authorization: Bearer <token>
X-Company-Id: <companyId>
Content-Type: application/json
{
"platform": "web",
"endpoint": "https://fcm.googleapis.com/fcm/send/…",
"keys": { "p256dh": "…", "auth": "…" }
}platform | Body |
|---|---|
web | endpoint (subscription URL) + keys.p256dh + keys.auth |
ios / android | endpoint = FCM/device token |
Also: GET /notifications/devices (your own list) and DELETE /notifications/devices/:deviceId (unregister).
Host configuration (VAPID / FCM): see the notification architecture documentation.
API — Scheduled sends and history
Same authorization as the immediate send (OWNER/ADMIN JWT or sk_ OWNER/ADMIN).
Scheduling
POST /notifications/schedule
Authorization: Bearer <token>
X-Company-Id: <companyId>
Content-Type: application/json
{
"mode": "broadcast",
"title": "Notice",
"body": "Tomorrow",
"scheduledAt": "2030-01-15T10:00:00.000Z"
}scheduledAt must be a future instant (UTC); otherwise → 400. destination follows the same rules as the immediate send: omitting it is valid; null, empty, unsafe schemes and protocol-relative URLs → 400. Response 201 with the outbox row (status: scheduled). If delivery fails it is retried up to 3 times; after that it stays failed with failedAt and lastError, and the actor who scheduled it is notified.
When the instant arrives, an in-process poller (~10s) claims due rows and runs them through the same pipeline as the immediate send. It requires no Redis.
Listing and cancelling pending sends
GET /notifications/scheduled?page=1&limit=20
POST /notifications/scheduled/:id/cancelBy default OWNER/ADMIN/sk_ see the tenant's pending sends; ?own=true narrows it to the actor. Cancelling after execution → 409, and it does not revert deliveries.
Your own history vs the tenant's global listing
| Endpoint | What it lists | Who |
|---|---|---|
GET /notifications/sends | Outbox of sends originated by the actor (immediate + scheduled): id, mode, content/template, requested channels, status, timestamps; failures include failedAt and lastError | OWNER/ADMIN/sk_ |
GET /notifications/tenant | Every in-app notification of the tenant (system + manual) | OWNER/ADMIN/sk_; MEMBER → 403 |
The history never changes when a template is edited or deleted: both the outbox (/notifications/sends) and the in-app notifications (/notifications and /notifications/tenant) store what was sent or rendered at send time — never a live reference to a notification_templates row. Editing or deleting a system or company template after a send neither alters nor invalidates that history.
API — In-app notifications
In-app notifications are read and marked as read through the API.
Listing notifications
GET /notifications?page=1&limit=20
Authorization: Bearer <token>
X-Company-Id: <companyId>Optional ?unread=true parameter to see only unread ones.
Pagination — page (default 1) and limit (default 20, maximum 100) are optional. A page out of range is not an error: it returns data: [] with total reflecting the real count.
Response:
{
"data": [
{
"id": "uuid",
"notificationType": "USER_INVITED",
"title": "You've been invited",
"body": "You've been invited to join as member.",
"metadata": { "role": "member" },
"destination": null,
"readAt": null,
"createdAt": "2024-01-01T10:00:00Z"
}
],
"total": 1,
"page": 1,
"limit": 20
}destination is an optional internal navigation route for the host; in a free send it must start with / and accepts neither schemes nor // URLs. It comes from metadata.destination; legacy notifications without a destination return null.
Live channel (SSE)
A channel additive to the REST listing: the SDK/host subscribes to receive in-app notifications in real time.
- Obtain a ticket (session JWT + active company):
POST /notifications/realtime/ticket
Authorization: Bearer <token>
X-Company-Id: <companyId>Response: { "ticket": "...", "expiresIn": 45 } (~45s, single use).
- Open the stream (EventSource cannot send Bearer):
GET /notifications/stream?ticket=<ticket>
Accept: text/event-streamnotification events with: id, title, body, type, destination, read, createdAt, unreadCount.
Switching company requires a new ticket. Fan-out is in-process (a single instance); multi-instance will need pub/sub later.
Marking a notification as read
POST /notifications/:id/read
Authorization: Bearer <token>Returns the updated notification with readAt set. If the notification does not belong to the user or the active tenant, it returns 403.
Marking all as read
POST /notifications/read-all
Authorization: Bearer <token>
X-Company-Id: <companyId>Returns 204 with no body.
Email and webhook
Email and webhook notifications are sent asynchronously in the background. The user does not wait for them — the HTTP request is not blocked.
Email uses the transport configured in MAILER_TRANSPORT. In log mode the message is not delivered: SMTP resolution is applied first and then only safe metadata is logged, without recipient, subject or content. If there is no usable SMTP provider or fallback, resolution fails.
The webhook POSTs to the URL configured in the webhook.url setting. If it is not configured, the webhook is silently skipped.
To configure the webhook:
PUT /settings/webhook.url
{ "value": "https://my-server.com/webhook" }Manageable system templates
Besides the fixed type catalogue above, a platform SUPER_ADMIN can administer a catalogue of notification templates with a name, required data fields and content (title/body, with placeholders). The ten fixed-catalogue types are migrated automatically into this catalogue (by code, e.g. USER_CREATED), without affecting the existing automatic sends. Deleting a template is a soft delete (deleted_at): it stops appearing in the listing/picker and the startup seed does not recreate it.
Endpoints (platform SUPER_ADMIN only)
| Method | Route | Description |
|---|---|---|
GET | /notifications/templates | List the system template catalogue (companyId null) |
GET | /notifications/templates/:id | Get a system template by id — 404 if the id belongs to a company-owned template |
POST | /notifications/templates | Create a system template |
PATCH | /notifications/templates/:id | Edit a system template — does not affect already sent notifications; 404 if the id is company-owned |
DELETE | /notifications/templates/:id | Delete a system template — does not affect already sent notifications; 404 if the id is company-owned |
Trying to read, edit or delete a company-owned template by id through these system routes answers 404 (not 403): the SUPER_ADMIN CRUD only reaches rows with a null companyId.
In the TypeScript SDK, the global CRUD is separated into client.systemNotificationTemplates and is only exposed in the Browser with a Super Admin JWT. The claim is checked locally for better feedback; the server re-authorizes every operation. The tenant CRUD stays in client.notifications (listTemplates, getTemplate, createTemplate, updateTemplate, deleteTemplate) and requires OWNER/ADMIN of the active company in the Browser.
Creation example:
POST /notifications/templates
Authorization: Bearer <super admin token>
{
"name": "Custom welcome",
"description": "Welcome template with a corporate tone",
"requiredFields": ["name"],
"content": {
"title": "Welcome!",
"body": "Hi {{name}}, your account is ready.",
"subject": "Welcome aboard"
}
}This management is independent from choosing a template in the manual send composer. Sending directly from a row of this catalogue is a separate iteration; today type only accepts the fixed NotificationType catalogue.
Unified listing for the send composer
An OWNER or ADMIN of the active company can list the system catalogue together with their own company templates in a single call — intended to populate the template picker of the manual send composer.
| Method | Route | Description |
|---|---|---|
GET | /notifications/templates/available | Unified listing: system catalogue + the active company's own templates (OWNER/ADMIN) |
GET /notifications/templates/available
Authorization: Bearer <owner/admin token>
X-Company-Id: <company-uuid>It never includes another company's own templates (per-tenant isolation). With no active company selected it answers 400.
Company-owned templates
Besides the system catalogue, any OWNER or ADMIN of a company can create their own templates — in the same format (name, required fields, content with placeholders) — for that company's exclusive use. They are fully isolated per tenant: a company never sees, edits or deletes another company's own templates.
Endpoints (OWNER/ADMIN of the active company)
| Method | Route | Description |
|---|---|---|
GET | /notifications/company-templates | List the active company's own templates |
GET | /notifications/company-templates/:id | Get an own template by id (404 if it belongs to another company) |
POST | /notifications/company-templates | Create an own template for the active company |
PATCH | /notifications/company-templates/:id | Edit an own template — does not affect notifications already sent with the previous version |
DELETE | /notifications/company-templates/:id | Delete an own template — does not affect already sent notifications |
Creation example:
POST /notifications/company-templates
Authorization: Bearer <owner/admin token>
{
"name": "Order confirmation",
"requiredFields": ["orderId"],
"content": {
"title": "Order confirmed",
"body": "Your order {{orderId}} was confirmed."
}
}Trying to read, edit or delete another company's own template answers 404 (not 403), so the existence of that id is neither confirmed nor denied to a foreign tenant. An OWNER and an ADMIN of the same company have exactly the same permissions over their own templates — there is no hierarchy between the two roles in this iteration.
The tenant CRUD is also available in the server and browser SDKs, separate from the global system catalogue.
Preferences
By default every notification is enabled. A user can disable a specific type or channel — this is stored in notification_preferences.
| Method | Route | Description |
|---|---|---|
GET | /notifications/preferences | Lists the authenticated user's explicit preferences in the active company |
PUT | /notifications/preferences | Enables/disables a type+channel pair ({ type, channel, enabled }). Invalid type or channel → 400. The userId comes from the session, never from the body |
PUT /notifications/preferences
Authorization: Bearer <token>
X-Company-Id: <companyId>
Content-Type: application/json
{
"type": "USER_INVITED",
"channel": "email",
"enabled": false
}With no row for a type/channel, the system assumes enabled: true.
Multi-tenancy
Every notification is isolated by tenantId. An authenticated user in company A never sees company B's notifications. The query always combines userId + tenantId.
How notifications are generated
Notifications are created automatically from domain events:
UserInvitedEvent
↓ NotificationEventListener listens
↓ NotificationsService.notify()
↓ for each enabled channel:
in-app → stored in the database
email → async job → sent by emailYou do not need to call the notification service directly. The system events do it automatically.
Beta tester feedback (the floating widget) is a special case: it does not belong to a tenant, so instead of notifying a company's members it notifies every platform super administrator when new feedback arrives:
FeedbackCreatedEvent ('feedback.created')
↓ NotificationEventListener listens
↓ looks up every user with isSuperAdmin === true
↓ NotificationsService.notify() for each super administrator
in-app → stored in the database (type FEEDBACK_RECEIVED)Extensibility
To add a new channel (e.g. mobile push, SMS):
- Implement the
NotificationChannelServiceinterface - Add it as a provider in
NotificationsModule - Register the channel in
NotificationsService.getChannelService()
To add a new notification type:
- Add the value to the
NotificationTypeenum - Add the channel renderer in
template.registry.ts(channel matrix + fallback) - Add the entry in
system-catalog.seed.ts(contentwith— the runtime render source) - If it is triggered by an event, add the listener in
NotificationEventListener