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>"}}

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 (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.
• A client subscribed at org level receives events for all orders; specific-order and org-level subscriptions can coexist.

GET /ws

Error

A valid request URL is required to generate request examples

400

{
  "code": 400,
  "error": "Bad Request",
  "message": "Invalid request parameters"
}

Response

101

Switching Protocols - WebSocket connection established