Publishing and subscribing

Publish an event over HTTP, and receive your tenant's over SSE or WebSocket - with no broker client. Messages are CloudEvents 1.0.

Product side: Asynchronous plane and brokers; operations side: Publishing and consuming on a broker.

Publishing

curl -i -X POST https://api.example.com/orders/events -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -H 'Idempotency-Key: order-42' -d '{"orderId":"42"}'
# HTTP/1.1 202 Accepted   {"id":"order-42"}

Response	Meaning	What to do
202	The broker acknowledged the message	Nothing
428 idempotency_key_required	The door requires Idempotency-Key	Add it
504 upstream_timeout	Unknown outcome: the message may have been written	Send again with the same Idempotency-Key - it becomes the id, consumers deduplicate
503 overloaded	The gateway's buffer is full	Wait Retry-After
503 upstream_unavailable	The broker is unreachable	Wait Retry-After
400	You sent a ce-* header: the attributes are the gateway's	Remove it
415, 422	A body of another type, or outside the schema	Fix it

The tenant, id, source and trace are set by the gateway. Order is guaranteed per message key only.

Subscribing over SSE

curl -N https://api.example.com/orders/stream -H "Authorization: Bearer $TOKEN" -H 'Accept: text/event-stream'
# id: 0:18,1:7,2:11
# event: created
# data: {"specversion":"1.0","id":"order-42","tenant":"acme","data":{"orderId":"42"},...}

Rule	Detail
Resumption	Come back with Last-Event-ID: reading resumes from the channel's recent history
Beyond the history	412 precondition_failed: open again without Last-Event-ID
Too slow a subscriber	Closed (event: error, overloaded)
Number of streams	Capped per caller
Binary payloads	Received as JSON (datacontenttype: application/json)

Subscribing over WebSocket

Each message is a JSON CloudEvent; acknowledge it within the announced delay:

ws.onmessage = (m) => {
  const ev = JSON.parse(m.data);
  handle(ev);
  ws.send(JSON.stringify({ ack: ev.id }));
};

Close	Meaning
1008	A refusal, or a missing acknowledgement within the delay: the message is delivered again on reconnection (at least once)
1011	The broker is down: reconnect after a delay
1013	Too slow a subscriber

The last message before the close carries the RFC 9457 problem. Deduplicate on source + id.