If You Are Used to Polling APIs

Previously, you might have sent a GET request every few minutes to receive a list of recent events. With WebSockets, you:

  1. Connect once.
  2. Authenticate by sending a connection_init JSON message with your oAuth token.
  3. Send a subscription request.
  4. Send regular ping requests and reply with pong to server pings to keep the connection open.
  5. Wait and process events as they stream in. There is no need to poll. Each event will be a JSON next message.
  6. Exchange heartbeat messages to keep the connection open.
  7. When done, send a complete message, but wait for the server to close the connection.

You only need to reconnect if the connection drops or if your authentication expires.

  Polling API Streaming API (WebSocket)
API Complexity Simple Requires ping/pong, reconnection, etc.
Connection New connection for each poll Persistent once-open connection
Data Arrival On schedule (e.g., every N minutes) Near-real-time delivery after the event is emitted
Network Load High (many HTTP requests) Low (connection stays open)
Sample Output List of events; may contain duplicates Single event per message; processed sequentially
Delta - only changed events Set Delta Only flag in External System Send 'delta: true' in subscribe request

Migrating from Polling APIs to the Streaming API

When migrating an integration from a polling API to the Streaming API, run both consumers concurrently until you confirm that the Streaming API is receiving the same events as the polling API.

During this overlap period, implement duplicate detection across both delivery methods. Create a hash from all the event headers except:
  • uniqueEventId
  • externalSystemCode

Do not include uniqueEventId because it identifies an individual delivery. Do not include externalSystemCode because the polling consumer and streaming consumer use different external system codes. Excluding these fields produces the same hash when the same event is received through both APIs.

Store and compare the hashes received from each delivery method. Continue polling until an event received through the Streaming API has the same hash as an event already received through the polling API.

When the first matching event is detected, the overlap has been confirmed. Stop polling and continue processing events through the Streaming API only. This approach prevents the same event from being processed twice during migration.