Skip to main content

WebSocket API Reference

AiSOC streams real-time events over an authenticated WebSocket connection served by the realtime service (port 8086).

Connection​

wss://your-domain.com/ws?token=<jwt>

Locally:

ws://localhost:8086/ws?token=<jwt>

Pass a valid JWT in the token query parameter. The connection is rejected with 4001 Unauthorized if the token is missing or expired.

Message Format​

All messages are JSON objects with a type field:

{
  "type": "alert.created",
  "payload": { ... },
  "tenant_id": "uuid",
  "ts": "2026-05-03T10:00:00Z"
}

Server → Client Events​

Alerts​

TypeDescription
alert.createdNew alert ingested
alert.updatedAlert status / severity changed
alert.assignedAlert assigned to analyst

Cases​

TypeDescription
case.createdNew case opened
case.updatedCase fields updated
case.commentComment added
case.closedCase closed

Investigations (AI Copilot)​

TypeDescription
investigation.startedAgent investigation begun
investigation.stepIntermediate reasoning step
investigation.findingFinding added to case
investigation.completedInvestigation finished
investigation.errorInvestigation failed

Detections​

TypeDescription
detection.triggeredRule fired
detection.suppressedDetection suppressed by a rule

UEBA​

TypeDescription
ueba.anomalyBehavioral anomaly detected
ueba.baseline_updatedBaseline recalculated

Honeytokens​

TypeDescription
honeytoken.touchedToken accessed / triggered

Playbooks​

TypeDescription
playbook.startedPlaybook execution started
playbook.stepStep completed
playbook.completedPlaybook finished
playbook.failedPlaybook failed

System​

TypeDescription
pingServer keepalive (every 30 s)
errorProtocol or server error

Client → Server Messages​

Subscribe to a channel​

{
  "type": "subscribe",
  "channel": "alerts"
}

Available channels: alerts, cases, detections, investigations, ueba, honeytokens, playbooks, all.

Unsubscribe​

{
  "type": "unsubscribe",
  "channel": "alerts"
}

Pong (keepalive reply)​

{ "type": "pong" }

Example (Browser)​

const ws = new WebSocket(`ws://localhost:8086/ws?token=${jwt}`);

ws.onopen = () => {
  ws.send(JSON.stringify({ type: "subscribe", channel: "all" }));
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  if (msg.type === "alert.created") {
    console.log("New alert:", msg.payload);
  }
};

React Hook​

The Next.js frontend exposes a useRealtimeEvents hook:

import { useRealtimeEvents } from "@/hooks/useRealtimeEvents";

function AlertFeed() {
  const events = useRealtimeEvents(["alert.created", "alert.updated"]);
  return <ul>{events.map(e => <li key={e.payload.id}>{e.payload.title}</li>)}</ul>;
}