Realtime
Subscribe to live account and assistance events over a WebSocket using a short-lived ticket.
Realtime
Reconbanker pushes live events — a login asking for a code, a scrape finishing, a session starting — to the dashboard over a WebSocket. This page documents that stream.
It is meant for a logged-in UI. If you are building a server-to-server integration, prefer the notification webhook (push) or the External API status endpoint (poll); both work without holding a socket open and without a user token.
Get a ticket
A WebSocket cannot carry an Authorization header through the browser, so you first exchange your JWT for a short-lived ticket.
POST /realtime/ticket
Authorization: Bearer <jwt>Response 200 OK:
{ "ticket": "<jwt>", "ttl_seconds": 30 }The ticket is scoped only to opening a WebSocket — it does not authorize the REST API — and it expires after ttl_seconds (30 by default). Request it immediately before connecting.
Open the WebSocket
Connect to /realtime on your instance:
wss://reconbanker.your-domain.com/realtimeDuring local development this is ws://localhost:3000/realtime.
Pass two values in the Sec-WebSocket-Protocol header (the WebSocket subprotocol list): the fixed protocol name realtime.v1, then your ticket.
Sec-WebSocket-Protocol: realtime.v1, <ticket>The server validates the ticket, authenticates you, and then streams events for the accounts you own.
Event stream
Each message is a JSON object:
{
"type": "assistance.requested",
"userId": "user-1",
"accountId": "b9c224b3-3c2b-42bd-b23e-337ae0185690",
"data": { "descriptor": { "length": 6, "type": "numeric" } },
"occurredAt": "2026-06-13T03:00:00.000Z"
}Filter on type:
type | Fires when |
|---|---|
assistance.requested | A login is waiting for a one-time code. data carries the OTP descriptor. |
assistance.fulfilled | A code was submitted and the login is progressing. |
assistance.cancelled | The pending request was cancelled. |
login.failed | A bank login failed. |
scrape.failed | A scrape failed. |
scrape.succeeded | A scrape completed. |
session.started | A bank session opened. |
session.stopped | A bank session closed. |
occurredAt is an ISO 8601 timestamp.
Relationship to notifications
The notification webhook delivers a subset of these events to an external endpoint under slightly different names — for example, assistance.requested here maps to assistance_required there. For servers, prefer the webhook or the External API; this WebSocket is for live dashboard updates.
See also
- Assisted login and OTP - the assistance lifecycle these events describe.
- Notification settings - the server-to-server equivalent.
- External API - poll status instead of streaming events.