Idempotent Receiver

An Idempotent Receiver is a consumer designed so that receiving the same message multiple times produces the same result as receiving it once. It absorbs the duplicate deliveries that are inherent in reliable messaging, turning at-least-once delivery into effectively exactly-once processing.

The problem it solves is duplicate messages. Almost all practical messaging guarantees at-least-once delivery: a consumer crash after doing work but before acknowledging, a redelivery after a visibility timeout, or a producer retry can all deliver the same message twice. Without protection, duplicates cause double charges, double shipments, or corrupted counts.

How It Works

The receiver detects or tolerates duplicates. The common approach is deduplication by identifier: each message carries a unique id (often a correlation or business id), and the receiver records processed ids in a store. Before acting it checks whether the id was already handled; if so it skips the work but still acknowledges. The dedup record and the side effect should be committed together, or the side effect itself should be naturally idempotent.

A second approach is to design operations to be inherently idempotent — set a status to SHIPPED rather than increment a counter, or use an upsert keyed by business id — so reprocessing is harmless without explicit tracking.

if seen(messageId): ack and skip
else: process(); record(messageId); ack

When to Use It

Use it with any at-least-once messaging system, with competing consumers, with producer retries, and wherever guaranteed delivery is in play — which is almost always. It is essential for financial, inventory, and stateful operations where duplicates cause real harm.

Avoid skipping it on the assumption of exactly-once delivery; true end-to-end exactly-once is rare and usually achieved precisely by combining delivery guarantees with idempotent receivers.

Trade-offs

Idempotency adds a dedup store or constraints on operation design, plus the cost of checking and recording ids and managing their retention. Getting atomicity right (dedup record plus side effect) can be subtle, especially across separate systems. The payoff is correctness under the duplicate deliveries that real messaging guarantees.

Related Patterns

It complements Guaranteed Delivery and Competing Consumers, which both create duplicate risk. A Correlation Identifier provides the unique key. A Dead Letter Channel handles messages that fail even after safe retries.

Example

A payment service stores each processed payment under a unique idempotency key supplied by the producer. If the charge message is redelivered, the service finds the key already recorded, returns the prior result, and does not charge the card again — the effect is exactly one charge despite multiple deliveries.