Order Status WebSocket

Upgrade to a WebSocket connection to receive real-time order status events.

Authentication is performed over the WebSocket protocol using a connect message, so no HTTP headers are required during the upgrade handshake.

Protocol

Step 1 - Authenticate (must be the first message sent):

{"type":"connect","data":{"api_key":"<your_api_key>"}}

For organization-wide subscriptions, include an authorization signature generated for GET /ws:

{"type":"connect","data":{"api_key":"<your_api_key>","authorization_signature":"APIKey=<your_api_key>,signature=<signature>,timestamp=<timestamp>"}}

Server responds on success:

{"type":"connected","data":{"status":"authenticated"}}

Step 2 - Subscribe to a specific order:

{"type":"subscribe","data":{"order_id":"<id>"}}

Server responds:

{"type":"subscription","data":{"order_id":"<id>","scope":"order","status":"subscribed"}}

Subscribe to all orders in your organization (requires signed connect; omit order_id or leave it empty):

{"type":"subscribe","data":{}}

Server responds:

{"type":"subscription","data":{"scope":"organization","status":"subscribed"}}

Unsubscribe from a specific order:

{"type":"unsubscribe","data":{"order_id":"<id>"}}

Unsubscribe from all org orders:

{"type":"unsubscribe","data":{}}

Server push - Order event:

{"type":"event","data":{...order event payload...}}

Server message types:

• connected - authentication succeeded
• subscription - confirms subscribe/unsubscribe; includes scope ("order" or "organization")
• event - real-time order status change
• error - describes what went wrong (e.g. invalid api_key, not authenticated, access denied)

Notes:

• Clients must send connect before any subscribe/unsubscribe messages.
• Clients can only subscribe to orders belonging to their own organization.
• Organization-wide subscriptions require a valid authorization_signature; API-key-only connections can subscribe to specific orders only.
• A client subscribed at org level receives events for all orders; specific-order and org-level subscriptions can coexist.