Real-time Notifications

WebSocket push for in-app notifications and admin alerts

In-app notifications (GET /v1/notifications in the reference) are also pushed live over a Socket.IO connection, so a frontend doesn’t have to poll. Every notification that’s pushed live is also persisted — a client that connects late will still see it via the REST endpoint.

Connecting

Connect through api-gateway, not directly to any backend service — exactly like every REST call. The gateway terminates the WebSocket upgrade and proxies it internally.

import { io } from "socket.io-client";

const socket = io("https://asikodevapi.candourit.io", {
  path: "/v1/ws/notifications",
  auth: { token: accessToken }, // the same JWT access token used for REST
  transports: ["websocket"],
});

path must be exactly /v1/ws/notifications — this is a Socket.IO path (an HTTP-routable endpoint), not a namespace, since the gateway proxies on the raw path of the WebSocket upgrade request.

If you can’t set a custom auth payload (some Socket.IO client environments can’t), pass the token as a token query parameter instead: ?token=<accessToken>. A connection with no token, or an invalid/expired one, is disconnected immediately after the handshake.

Events you’ll receive

notification · event

Sent to the connected user whenever a new in-app notification is created for them — the same shape as an item from GET /v1/notifications.

{
  "id": "f8b002df-6857-4aa1-b7cb-ddf9318d5440",
  "userId": "a096a92b-9571-487e-a99c-978ae8d6c5df",
  "title": "You earned 5 points!",
  "content": "You earned 5 points for sharing a product.",
  "readAt": null,
  "createdAt": "2026-08-02T15:48:51.045Z"
}

admin-alert · event

Sent only to sockets authenticated as ADMIN or SUPER_ADMIN — an ephemeral ops ping (not persisted, not retrievable via REST) for things that need staff attention.

{
  "title": "New Wholesale Application - Acme Traders",
  "content": "New wholesale application from Acme Traders (tracking CRA-7806394). Needs review.",
  "createdAt": "2026-08-02T15:52:38.047Z"
}

What triggers a push

A notification event fires for any account-affecting action with a customer-facing template — registration, wholesale application status changes, order placed/paid/dispatched/delivered/ cancelled, password changes, and loyalty point awards (leaving a review, referring a friend, sharing a product). See the Domain Events Catalog for the exhaustive list of which actions currently trigger a notification versus which are defined but not yet wired.

An admin-alert fires for a smaller set of events ops needs to react to: new customer registration, new wholesale application, new order placed, and low stock.