Connection

Connection URL

Connect to EDS 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 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.

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 index page.