Skip to content

Notifications ​

The notification system sends alerts to users across several channels when relevant platform events happen.

Supported channels ​

ChannelHow it reaches the user
In-appAppears in the application panel
EmailSent to the user's address asynchronously
WebhookA POST to a URL configured by the tenant
Web pushBrowser Notification API (a registered Web Push subscription)
Native pushiOS / Android through a device token (FCM)

Each channel can be turned on or off per user and notification type.

Notification types ​

TypeWhen it fires
USER_CREATEDWhen a new account is created
USER_INVITEDWhen an invitation to a company arrives
USER_INVITATION_ACCEPTEDWhen an invitation is accepted
ROLE_CHANGEDWhen a user's role changes
EXPORT_READYWhen an export completes
PAYMENT_FAILEDWhen a subscription charge fails
SUBSCRIPTION_CHANGEDWhen a subscription is cancelled or modified
INVOICE_AVAILABLEWhen a new invoice is generated
TRIAL_ENDINGWhen the trial period is about to expire
FEEDBACK_RECEIVEDWhen new feedback arrives from the beta tester widget — every platform super administrator is notified in-app
CUSTOMFree 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.

http
POST /notifications/send
Authorization: Bearer <token>   # or X-API-Key: sk_…
X-Company-Id: <companyId>
Content-Type: application/json

Recipient modes

modeBehaviour
broadcastEvery current member of the company
usersClosed 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. Omitting destination is 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 (not CUSTOM). The API requires payload to include every requiredFields of the template; missing or blank keys → 400.

Channels (optional):

  • channels: list of in_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 → omissions with no_recipient_devices

Response: 202 Accepted with:

json
{
  "accepted": true,
  "channels": ["in_app"],
  "omissions": []
}

No per-recipient delivery state (send-and-forget). MEMBER → 403.

Free broadcast example:

json
{
  "mode": "broadcast",
  "title": "Company notice",
  "body": "All-hands tomorrow",
  "destination": "/announcements"
}

Multi-channel example:

json
{
  "mode": "users",
  "userIds": ["member-uuid"],
  "title": "Ping",
  "body": "Hello",
  "channels": ["in_app", "email", "native_push"]
}

List plus template example:

json
{
  "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).

http
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": "…" }
}
platformBody
webendpoint (subscription URL) + keys.p256dh + keys.auth
ios / androidendpoint = 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 ​

http
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 ​

http
GET /notifications/scheduled?page=1&limit=20
POST /notifications/scheduled/:id/cancel

By 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 ​

EndpointWhat it listsWho
GET /notifications/sendsOutbox of sends originated by the actor (immediate + scheduled): id, mode, content/template, requested channels, status, timestamps; failures include failedAt and lastErrorOWNER/ADMIN/sk_
GET /notifications/tenantEvery 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 ​

http
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:

json
{
  "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.

  1. Obtain a ticket (session JWT + active company):
http
POST /notifications/realtime/ticket
Authorization: Bearer <token>
X-Company-Id: <companyId>

Response: { "ticket": "...", "expiresIn": 45 } (~45s, single use).

  1. Open the stream (EventSource cannot send Bearer):
http
GET /notifications/stream?ticket=<ticket>
Accept: text/event-stream

notification 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 ​

http
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 ​

http
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:

http
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) ​

MethodRouteDescription
GET/notifications/templatesList the system template catalogue (companyId null)
GET/notifications/templates/:idGet a system template by id — 404 if the id belongs to a company-owned template
POST/notifications/templatesCreate a system template
PATCH/notifications/templates/:idEdit a system template — does not affect already sent notifications; 404 if the id is company-owned
DELETE/notifications/templates/:idDelete 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:

http
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.

MethodRouteDescription
GET/notifications/templates/availableUnified listing: system catalogue + the active company's own templates (OWNER/ADMIN)
http
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) ​

MethodRouteDescription
GET/notifications/company-templatesList the active company's own templates
GET/notifications/company-templates/:idGet an own template by id (404 if it belongs to another company)
POST/notifications/company-templatesCreate an own template for the active company
PATCH/notifications/company-templates/:idEdit an own template — does not affect notifications already sent with the previous version
DELETE/notifications/company-templates/:idDelete an own template — does not affect already sent notifications

Creation example:

http
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.

MethodRouteDescription
GET/notifications/preferencesLists the authenticated user's explicit preferences in the active company
PUT/notifications/preferencesEnables/disables a type+channel pair ({ type, channel, enabled }). Invalid type or channel → 400. The userId comes from the session, never from the body
http
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 email

You 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):

  1. Implement the NotificationChannelService interface
  2. Add it as a provider in NotificationsModule
  3. Register the channel in NotificationsService.getChannelService()

To add a new notification type:

  1. Add the value to the NotificationType enum
  2. Add the channel renderer in template.registry.ts (channel matrix + fallback)
  3. Add the entry in system-catalog.seed.ts (content with — the runtime render source)
  4. If it is triggered by an event, add the listener in NotificationEventListener