FAQ
Setup & Prerequisites
How do I obtain an API key and queue name?
Contact Empego. Both are required before you can connect.
How do I authenticate?
Pass Authorization: api-key {your-api-key} as a header on the WebSocket upgrade request.
What URL do I connect to?
wss://<host>/subscribe?queue={queueName} — contact Empego for the host value.
Connection & Keep-Alive
How often should I send pings?
Every 2–3 minutes. The API Gateway idle timeout is 10 minutes, so regular pings keep the connection alive.
What happens if I don’t send pings?
The server silently closes the connection after 10 minutes of no traffic. There is no 4xxx close code — just a bare close frame.
Can I open multiple connections to the same queue?
No. Only one active subscription per queue is allowed. A second connection attempt is rejected with close code 4409.
What is error code 4401?
Authentication failure. Fix the API key and do not retry automatically.
What is error code 4409?
Duplicate subscription — another connection to this queue is already open. Wait for the existing connection to close before reconnecting. Stale connections auto-close after 10 minutes of inactivity.
What happens to events while I’m disconnected?
Events accumulate in the queue and are delivered in bulk when you reconnect.
Acknowledgement
What happens if I don’t acknowledge an event within 30 seconds?
The event becomes visible again and is redelivered with the same eventId but a new receiptId. See Delivery Guarantees for details.
Should I ack before or after processing?
Ack once the event is durably recorded (e.g. written to your database), not after all downstream processing completes. This minimises the risk of hitting the 30-second visibility timeout.
What should I use in the ack frame — eventId or receiptId?
Always use receiptId in the ack frame. Use eventId only for deduplication.
Deduplication
Can I receive the same event more than once?
Yes. EDS V2 guarantees at-least-once delivery; duplicates can occur after a redelivery. See Deduplication.
How do I deduplicate?
Maintain a set of seen eventId values. Skip business logic for known IDs but always send the ack.
Should I ack a duplicate event?
Yes. Failing to ack leaves the event in the queue, causing an infinite redelivery loop.
What is the difference between eventId and receiptId?
eventId is stable across all redeliveries — use it for deduplication. receiptId is unique per delivery attempt — use it in the ack frame.
Protocol
What message format does EDS V2 use?
JSON text frames with the envelope { "frameType": "...", "framePayload": { ... } }. See Protocol for the full reference.
Do I need to reply to pong frames?
No. Pong is the server’s response to your ping; no client reply is expected.
What frame types can the server send me?
EVENT, PONG, and ACK_EVENT_REPLY (confirming your acknowledgement).
Events
What events are currently delivered?
TENANT_ONBOARDED and TENANT_OFFBOARDED. Both include eventTs, queueName, eventId, and receiptId. See Events.
Best Practices & Reliability
How do I avoid missing the 30-second ack window if processing is slow?
Decouple receiving from processing: persist the event immediately, ack right away, then process asynchronously.
How should I handle reconnection?
Use exponential backoff with random jitter. Do not retry on 4401 — that requires a configuration fix, not a reconnect.