Realtime Fabric

The realtime fabric powers live updates across Capture, Payload, Retry, Scanner, and Tunnel labs. It exposes a WebSocket endpoint that broadcasts events on dedicated channels.

Establish a WebSocket session, subscribe to the topics you need, and process broadcasts as the realtime fabric fans them out.

Connect to the hub

1. Authenticate in the UI or call the session API to obtain a token.
2. Open a WebSocket connection to wss://<host>:9009/realtime?token=<session>.
3. Send a JSON payload specifying the channels to follow, for example:

{ "op": "subscribe", "topics": ["log.event", "payload.list", "tunnel.status"] }

The server responds with a confirmation event for each subscription.

Key topics

Topic	Description
log.event	System-level audit log showing auth and config changes.
capture.activity	New capture payloads and replay actions.
payload.list	Payload uploads, variant creation, and download counters.
retrylab.stats	Metrics updates for active retry scenarios.
scanner.jobs	Job lifecycle updates, run completions, and diff signals.
tunnel.status	Cloudflared heartbeat, hostname, and restart counters.

Broadcast filters

Include an optional scopes field in the subscribe message to limit noise:

{
  "op": "subscribe",
  "topics": ["payload.list"],
  "scopes": { "payloadId": "123" }
}

When scopes are present, LinkPeek only emits events whose metadata matches the provided keys.

Handling snapshots

Some topics emit a snapshot payload immediately after subscription. Use this to seed UI state before delta events arrive. Snapshots contain the same schema as individual events, with the snapshot boolean flag set to true.

Reconnect logic

Implement exponential backoff and resubscribe to topics after any disconnect. LinkPeek invalidates idle sessions, so keep-alive pings ({"op":"ping"}) every 30 seconds help avoid timeouts.

Server configuration

Environment variable	Purpose
REALTIME_ENABLED	Set to 0 to disable WebSocket support entirely.
REALTIME_TOPIC_LIMIT	Maximum number of simultaneous subscriptions per client. Default 32
REALTIME_ORIGINS	Comma-separated allowed origins for WebSocket upgrades.

Monitor the WebSocket health by tailing linkpeek logs or subscribing to the log.event stream, which records connect and disconnect events alongside client metadata.