Real-time & Webhooks

T-Suite pushes live updates — new notifications, wallet whitelist decisions, KYC and KYB approvals and similar — to signed-in users over a Server-Sent Events (SSE) stream. This page explains how the stream is opened and kept alive, and what exists today for webhooks.

How the stream works

• The stream is a long-lived text/event-stream response from the marketplace API, one per open browser tab.
• Each event is addressed to a single user; a user receives only their own events.
• Events originate in the backend services and reach the stream through Kafka, so an event raised by any service can be delivered live.
• The stream is a signal to refresh, not the source of truth. On an event, the client re-reads the relevant data (unread count, lists, the affected record) through the normal API.

Step 1 — get a one-time stream ticket

The browser’s EventSource cannot send an Authorization header, and putting an access token in a URL would leak it into logs and traces. So the stream is opened with a one-time ticket instead:

1. Make an authenticated POST to /auth/notifications/stream-ticket (under the /marketplace/v1 base path) with the user’s access token in the Authorization header.
2. The response contains a ticket and its lifetime in seconds.

Tickets are:

• Single-use — a ticket is consumed when the stream is opened, even if two requests race for it.
• Short-lived — a ticket expires 60 seconds after it is issued. Request it immediately before connecting.
• Bound to the session — when redeemed, the platform checks that the session that requested the ticket is still the account’s active session. If the user has signed out or signed in elsewhere, the ticket is refused.

Step 2 — open the stream

Open an EventSource on /auth/notifications/stream, passing the ticket as the ticket query parameter. The access token itself never appears in the URL.

On success the server sends:

Frame	Meaning
hello event	Sent once when the stream opens — the connection is live
Named events	One per update — for example notification, plus events for wallet whitelist requests and decisions, investor whitelist approvals, KYC and KYB approvals, and newly created offerings. Each carries a JSON payload
Heartbeat comment	Sent about every 25 seconds so proxies do not close an idle connection. Clients ignore it

The set of event names can grow as products add live updates. Handle unknown event names gracefully — refreshing notifications is a safe default.

Step 3 — reconnect correctly

Because every ticket works only once, the client — not EventSource’s built-in auto-reconnect — must own reconnection:

1. On error, close the EventSource.
2. Decide whether to retry.
   • If the stream never opened and the connection is closed, or the ticket request itself returned 401 or 403, the session is no longer valid. Stop. Reconnect only after the user signs in again.
   • Otherwise (network drop, server restart, 5xx), retry.
3. Back off exponentially — Libertum’s own app starts at 2 seconds and doubles up to a 30-second ceiling, resetting once a connection opens.
4. Fetch a fresh ticket for every attempt. Never reuse a ticket.

While the stream is down, fall back to periodic polling of the notifications API, and slow that polling down again once the stream is healthy.

Webhooks

Status: Coming soon

• There are no outbound customer webhooks yet. T-Suite does not currently call a URL that an issuer or partner registers when something happens on the platform. To react to events today, use the in-app notifications, email notifications, or — for signed-in users — the SSE stream described above.
• Inbound provider webhooks are internal. The platform receives callbacks from its own providers — for example SumSub (identity-verification results), Stripe (payments and subscriptions) and Bridge.xyz (T-Pay). Each is checked before it is processed — SumSub and Stripe callbacks by signature. These endpoints exist for those providers only and are not an integration surface for customers.

If your integration needs server-side event delivery, raise it with Libertum when scoping the integration.