WebSocket API¶

The WebSocket API provides real-time event streaming for workbook updates, job progress, and notifications.

Overview¶

CalcBridge WebSocket supports:

• Workbook Events: Real-time updates when workbook data changes
• Job Tracking: Live progress for export, reconciliation, and calculation jobs
• Notifications: Instant notification delivery
• Room-Based Subscriptions: Subscribe to specific resource channels

Connection¶

Main WebSocket Endpoint¶

wss://api.calcbridge.io/ws?token=<jwt_token>

Authentication is via JWT token passed as a query parameter.

Specialized Endpoints¶

Authentication¶

All WebSocket connections require a valid JWT token:

const ws = new WebSocket(
  `wss://api.calcbridge.io/ws?token=${accessToken}`
);

ws.onopen = () => {
  console.log('Connected to CalcBridge WebSocket');
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Event:', data.type, data.payload);
};

import websockets
import json

async with websockets.connect(
    f"wss://api.calcbridge.io/ws?token={access_token}"
) as ws:
    async for message in ws:
        event = json.loads(message)
        print(f"Event: {event['type']}")

Room Types¶

Workbook Events¶

Events received when connected to /ws/workbooks/{workbook_id}:

Example Event¶

{
  "type": "workbook.processing_progress",
  "payload": {
    "workbook_id": "550e8400-e29b-41d4-a716-446655440000",
    "progress": 75,
    "message": "Processing sheet 3 of 4"
  },
  "timestamp": "2026-01-25T10:30:05Z"
}

Job Events¶

Events received when connected to /ws/jobs/{job_id}:

Example Event¶

{
  "type": "job.completed",
  "payload": {
    "job_id": "job_xyz789",
    "result": {
      "rows_processed": 150,
      "duration_ms": 3200
    }
  },
  "timestamp": "2026-01-25T10:30:15Z"
}

Notification Events¶

Events received when connected to /ws/notifications:

Example Event¶

{
  "type": "notification",
  "payload": {
    "id": "notif_abc123",
    "title": "Export Complete",
    "message": "Your XLSX export is ready for download",
    "priority": "normal"
  },
  "timestamp": "2026-01-25T10:30:00Z"
}

Error Handling¶

Related Documentation¶

• Real-time - Real-time feature documentation
• Notifications API - Notification management