Connection

Connection URL

Connect to EDS V2 using a standard WebSocket upgrade request:

wss://eds.empego-dev-uat.name?queue={queueName}

Replace {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://eds.empego-dev-uat.name?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. 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.
  6. Disconnect — Client closes the WebSocket. The server detects the close, shuts down the subscription, and stops delivering events for this queue.
sequenceDiagram
    participant Client
    participant Server

    Client->>Server: WS upgrade + Authorization header
    Server-->>Client: 101 Switching Protocols

    Server-->>Client: EVENT frame
    Client->>Server: ACK_EVENT frame

    Server-->>Client: EVENT frame
    Server-->>Client: EVENT frame
    Client->>Server: ACK_EVENT frame
    Client->>Server: ACK_EVENT frame

    Client->>Server: PING frame
    Server-->>Client: PONG frame

    Client->>Server: close()
    Note over 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 409. 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

HTTP Status Code on connection:

Code Meaning Action
401 Authentication failure — missing API key Verify your API key and retry
403 Authentication failure — invalid API key or you’re not allowed to perform the EDS subscripton Verify your API key and retry
409 Duplicate subscription — a connection to this queue is already active Wait for the existing connection to close, then reconnect

Connection error handling

401 or 403

Do not retry; you need to fix the API key.

409

May occur if the subscription is already opened by another machine, or if a subscription has just been closed — upon disconnection, some resources are deallocated and that can take a couple of seconds. Perform a small delay (ex 1s) before retrying and retry for reasonable amount of time.

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