2 min lesson
Delivery guarantees & semantics
Use two rows in "Delivery guarantees & semantics" to state the practical decision rules.
Step 1 of 2
"Reliable" is not a single number. It is a choice between three failure modes and an engineering manager who owns webhooks for a tool at Cursor's scale has to name the choice out loud before designing anything.
The Cursor JD calls out webhook infrastructure with "proper retry semantics, dead-letter queues, idempotency and observability" in almost those words. When you answer a question in the loop, anchor to that vocabulary on purpose. It shows you read the charter and that you think in delivery guarantees, not vibes.
Start with the three semantics every event system picks from. Each one moves the pain to a different place.
- Semantic
- At-most-once
- What can go wrong
- Events can silently drop; no retry
- Where it fits
- Fire-and-forget metrics, low-value telemetry
- Semantic
- At-least-once
- What can go wrong
- Events can arrive more than once; consumer must dedup
- Where it fits
- The sane default for webhooks and most event delivery
- Semantic
- Exactly-once
- What can go wrong
- Impossible end to end in a distributed system; only approximated
- Where it fits
- A marketing claim unless you read the fine print
| Semantic | What can go wrong | Where it fits |
|---|---|---|
| At-most-once | Events can silently drop; no retry | Fire-and-forget metrics, low-value telemetry |
| At-least-once | Events can arrive more than once; consumer must dedup | The sane default for webhooks and most event delivery |
| Exactly-once | Impossible end to end in a distributed system; only approximated | A marketing claim unless you read the fine print |
Exactly-once delivery is not real across a network. Exactly-once processing is real and you get it by pairing at-least-once delivery with an idempotent receiver.
The sender cannot tell the difference between "the receiver never got it" and "the receiver got it but the ack was lost." Faced with that ambiguity it must either resend (risking a duplicate) or not (risking a loss). There is no third option over an unreliable network. So you choose at-least-once and push correctness onto the consumer, which is the one place you can actually enforce it.