WebSockets

Receive real-time order updates on your server without polling.

OZZOBiT WebSockets provide a real-time, bidirectional communication channel for receiving order status updates instantly. Unlike webhooks which require you to manage an HTTP endpoint, WebSocket connections allow your application to subscribe to order events and receive updates as they happen.

Overview

The WebSocket API is ideal for applications that need real-time order tracking, such as dashboards, trading interfaces, or any scenario where immediate feedback is critical. You can connect to our WebSocket server and receive push notifications for specific orders or all orders associated with your partner account.

Connection Details

Property	Value
WebSocket URL	wss://OZZOBiT.com/ws
Protocol	WSS (Secure WebSocket)
Authentication	API Key in connection params
Message Format	JSON
Heartbeat	30 seconds interval
Max Reconnect Attempts	5

ℹ️

When to Use WebSockets vs Webhooks

Use WebSockets: Real-time dashboards, live order tracking UIs, client-side applications
Use Webhooks: Server-side processing, database updates, payment confirmations, compliance logging

Supported Events

Event	Description	Data Included
ORDER_CREATED	New order initiated	orderId, amount, currency
ORDER_PROCESSING	Payment being processed	orderId, current step
ORDER_COMPLETED	Order finished successfully	orderId, txHash, amounts
ORDER_FAILED	Order failed	orderId, reason, errorCode
ORDER_CANCELLED	Order was cancelled	orderId, cancelledBy
KYC_STATUS_CHANGED	KYC verification updated	userId, newStatus
PONG	Response to heartbeat ping	timestamp

Connecting to WebSocket

websocket-connection.jsjavascript

// Browser / Node.js example
import { io } from 'socket.io-client'

const socket = io('wss://OZZOBiT.com/ws', {
  auth: {
    apiKey: 'YOUR_API_KEY'
  },
  transports: ['websocket'],
  reconnection: true,
  reconnectionAttempts: 5,
  reconnectionDelay: 1000,
})

socket.on('connect', () => {
  console.log('Connected to OZZOBiT WebSocket:', socket.id)
  
  // Subscribe to a specific order
  socket.emit('subscribe:order', { orderId: 'your-order-id' })
  
  // Or subscribe to all orders for this partner
  socket.emit('subscribe:partner')
})

socket.on('order:update', (data) => {
  console.log('Order update received:', data)
  
  switch (data.event) {
    case 'ORDER_COMPLETED':
      // Handle successful completion
      break
    case 'ORDER_FAILED':
      // Handle failure
      break
    case 'ORDER_PROCESSING':
      // Update UI with processing state
      break
  }
})

socket.on('disconnect', (reason) => {
  console.log('Disconnected:', reason)
})

socket.on('connect_error', (error) => {
  console.error('Connection error:', error.message)
})

Authentication

WebSocket connections require authentication using your OZZOBiT API key. Pass the API key in the auth object during connection setup as shown above.

Auth Parameter	Type	Required	Description
apiKey	string	Yes	Your OZZOBiT partner API key
env	string	No	Environment: 'STAGING' or 'PRODUCTION' (default: PRODUCTION)

⚠️

Security Best Practices

Never expose your API key in client-side code for production applications
Use environment variables or server-side proxy for API key management
Validate all incoming messages on your server before acting on them
Implement rate limiting on your WebSocket message handlers