Skip to main content

WebSocket: Order Status Updates

Get instant order status updates pushed to your application in real-time instead of polling the REST API.

Connection

Authentication

Include your API credentials in the Authorization header during the WebSocket handshake:
The server performs a quick format check on the header before upgrading the connection. If the header is missing or malformed, the connection is rejected at the HTTP level: Once the WebSocket connection is established, the server verifies your credentials asynchronously. On success you receive a welcome message. If credentials are invalid, you receive an error message with code AUTH_FAILED and the connection is closed with WebSocket close code 4401.

Quick Start

Message Protocol

All messages are JSON objects with a type field.

Client → Server

subscribe

Subscribe to order status updates. Send without houdiniIds to receive updates for all your orders, or specify an array to watch specific orders.
Subscribe to all orders
Subscribe to specific orders
Subscriptions are additive. Sending multiple subscribe messages with different houdiniIds adds to your watch list. Sending a subscribe without houdiniIds switches to all-orders mode.

unsubscribe

Stop receiving updates. Send without houdiniIds to unsubscribe from everything, or specify an array to stop watching specific orders.
Unsubscribe from all
Unsubscribe from specific orders
If you are subscribed to all orders and send an unsubscribe with specific houdiniIds, this resets your subscription to none. To continue receiving updates for other orders, re-subscribe after unsubscribing.

ping

Application-level keepalive. The server responds with pong.
The server also sends WebSocket-level pings every 30 seconds. Most WebSocket libraries handle these automatically. The application-level ping/pong is optional — use it if you want to measure round-trip latency.

Server → Client

welcome

Sent immediately after a successful connection.

order_update

Pushed whenever an order’s status changes. The data field contains the full order object — the same shape as GET /v2/orders/{houdiniId}.

subscribed

Confirmation after a subscribe message.
When subscribed to all orders

unsubscribed

Confirmation after an unsubscribe message.
When unsubscribed from all
When unsubscribed from specific orders

error

Sent when the server cannot process a client message.

Order Status Codes

The status field in order_update is a numeric code: Terminal statuses (no further updates): FINISHED, EXPIRED, FAILED, REFUNDED, DELETED.

Reconnection

The server does not persist subscriptions across disconnects. If your connection drops:
  1. Reconnect with credentials
  2. Re-send your subscribe message
  3. Optionally call GET /v2/orders to catch any updates you missed
Recommended strategy: exponential backoff starting at 1 second, capped at 30 seconds.

Security Notes

  • Only orders belonging to your partner account are delivered. You cannot receive updates for other partners’ orders.
  • The Authorization header format is validated during the HTTP upgrade. Credentials are verified immediately after the WebSocket connection is established.
  • Anonymous/private swap orders have their routing path censored from the response.