Websocket

Order Status WebSocket

get

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:

Server push - Order event:

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.

Responses
get
/ws

No content

Last updated