Ordering and idempotency

Deliveries are at least once and, by default, concurrent. Both have consequences on your side.

Idempotency, first

Store id. If you’ve seen it, return 200 and do nothing. A duplicate isn’t a bug: a timeout after your server committed looks exactly like a failure, so the retry is correct and the dedupe is yours.

Ordering, second

Fewer integrations need it than ask for it.

{ "deliveryMode": "ORDERED" }

An ordered endpoint gets two exact properties:

• Single-flight. Never two requests to that endpoint at once.
• No overtaking. While one delivery is retrying, nothing behind it is sent.

And the price

• The endpoint is at most as fast as its own round trip.
• One delivery that dead-letters blocks the queue behind it until it’s replayed or skipped.
• Ordering is per endpoint. Two endpoints may see events in different orders relative to each other.
• A strict total order across every event is best-effort.

Most people asking for ordering want “tell me when it happened and let me sort”. Every envelope carries createdAt, and every data block carries its own timestamp. Sort on those and stay UNORDERED.