Architecture Center
Idempotent outbound effects
Isolate the fragment that makes any outbound effect safe under retries and duplicate delivery, so it can be reused across integrations.
previewpatternContract >=0.8 <1.0Reviewed 2026-07-20
Problem statement
Networks retry and events get delivered more than once. Without an idempotency key an effect can apply twice; the pattern binds a key to a logical operation and returns the original receipt on replay.
When to use
- Any command that produces an external effect.
- Consumers that may redeliver the same event.
- Flows that must guarantee at-most-once application.
When not to use
- Purely internal state changes with no external effect.
- Naturally idempotent writes where a key adds no safety.
Flow
Command + idempotency keyKernel dedupe checkEffect (first time only)ReceiptReplay returns original receipt
Resource inventory
- Idempotency key
- Binds a retry to one logical operation.
- Effect
- Runs at most once for a given key.
- Receipt
- Returned verbatim on replay.
Failure modes
- Key reused with different args
- Rejected as an idempotency conflict; use a fresh key.
- Retryable failure
- Retry with the same key; applies at most once.
Security controls
- Keys scoped per tenant and operation.
- Receipts are immutable and auditable.
Deployment checklist
- Key derivation is stable per logical operation.
- Replays return the original receipt.
- Conflicts surface a clear error.
Related quickstart: Inspect a receipt →