Skip to content

WebSocket

CalcBridge uses WebSocket connections for real-time event streaming.

Connection

Endpoints

Endpoint Description Auto-Subscription
/ws General purpose Manual
/ws/workbooks/{id} Workbook events workbook:{tenant}:{id}
/ws/jobs/{id} Job progress job:{id}
/ws/notifications User notifications notifications:{user_id}

Authentication

All connections require a valid JWT token as a query parameter:

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

Connection Lifecycle

sequenceDiagram
    participant Client
    participant Server

    Client->>Server: Connect with JWT token
    Server->>Server: Validate token
    Server-->>Client: Connection accepted
    Client->>Server: Subscribe to rooms
    Server-->>Client: Subscription confirmed
    loop Events
        Server-->>Client: Event message
    end
    Client->>Server: Close connection

Room Types

Workbook Room

Pattern: workbook:{tenant_id}:{workbook_id}

Events: - workbook.status_changed - workbook.processing_started - workbook.processing_progress - workbook.processing_completed - workbook.processing_failed - sheet.data_updated

Job Room

Pattern: job:{job_id}

Events: - job.started - job.progress - job.completed - job.failed - job.cancelled - job.retrying

Notification Room

Pattern: notifications:{user_id}

Events: - notification - alert

Event Format

All events follow a consistent format:

{
  "type": "event.name",
  "payload": {
    "key": "value"
  },
  "timestamp": "2026-01-25T10:30:00Z"
}

Error Codes

Code Description
4001 Invalid or expired JWT token
4003 Insufficient permissions
4008 Connection timeout