Connection

Connection URL

Connect to EDS V2 using a standard WebSocket upgrade request:

wss://<host>/subscribe?queue={queueName}

Replace <host> with the Empego API host for your environment and {queueName} with the queue name assigned to your integration.

Authentication

Pass your integration API key in the Authorization header of the WebSocket upgrade request:

Authorization: api-key {your-api-key}

Most WebSocket client libraries support setting headers on the initial HTTP upgrade request.

Connection Flow

The full lifecycle of an EDS V2 connection:

  1. Connect — Client opens a WebSocket to wss://<host>/subscribe?queue={queueName} with the Authorization header.
  2. Authenticated — Server accepts the upgrade. The connection is now active and the queue subscription is open.
  3. Receive events — Server pushes EVENT frames as events become available in the queue.
  4. Acknowledge — Client sends an ACK_EVENT frame for each received event using the receiptId from the event frame. Acknowledge within 30 seconds to avoid redelivery (see Deduplication).
  5. Confirmation — Server responds with an ACK_EVENT_REPLY frame confirming the acknowledgement.
  6. Keep alive — Client sends periodic PING frames; server responds with PONG frames. Send a ping every 2–3 minutes to stay well under the 10-minute API Gateway idle timeout. If no messages flow in either direction for 10 minutes, the server silently closes the connection — there is no 4xxx code, just a bare close event. Treat this like any other transient disconnect and reconnect with exponential backoff.
  7. Disconnect — Client closes the WebSocket. The server detects the close, shuts down the subscription, and stops delivering events for this queue.
Client                          Server
  |                               |
  |-- WS upgrade + Auth header -->|
  |<-- 101 Switching Protocols ---|
  |                               |
  |<-------- EVENT frame ----------|
  |--------- ACK_EVENT frame ----->|
  |<------ ACK_EVENT_REPLY frame --|
  |                               |
  |--------- PING frame ---------->
  |<-------- PONG frame -----------|
  |                               |
  |-- close() ------------------>|
  |   [server closes subscription, stops delivery]

One Active Subscription Per Queue

Only one WebSocket connection may be subscribed to a given queue at a time. If a second client attempts to connect to the same queue while a connection is already active, the server rejects the new connection with error code 4409. When reconnecting, close the existing connection cleanly before opening a new one; stale connections (lost without a clean close) are closed automatically after 10 minutes.

Event Buffering While Disconnected

Events continue to accumulate in the queue while your client is disconnected. When you reconnect and open a new subscription, buffered events are delivered immediately. Combined with deduplication, this means your client will not miss events due to temporary disconnections.

Error Codes

EDS V2 uses WebSocket close codes in the 4xxx range to signal application-level errors:

Code Meaning Action
4401 Authentication failure — missing or invalid API key Verify your API key and retry
4409 Duplicate subscription — a connection to this queue is already active Wait for the existing connection to close, then reconnect

For reconnection logic, see the Quick Start pseudo-code on the EDS V2 index page.