Idempotent Consumer

Overview

An Idempotent Consumer processes a message, webhook, or event so receiving the same logical input multiple times does not create additional business side effects. It differs from transport deduplication because it protects the business operation even when duplicates have different delivery attempts or enter through different paths.

The main risks include double ledger entries, repeated fulfillment, duplicate payouts, race conditions, and acknowledgement before durable processing. It is essential when delivery is at least once or acknowledgement can be lost. The Idempotent Consumer policy should define which failures are retryable, how long the decision remains valid, and how duplicate effects are prevented.

In production, teams should define ownership and apply event or business keys, atomic deduplication with state changes, replay-safe handlers, immutable logs, and deterministic result handling. The Idempotent Consumer implementation should bound attempts, preserve the original operation identity, and stop before retries amplify a dependency failure.

Useful measures include deduplication hit rate, duplicate side effects, consumer retry rate, and processing recovery time. Idempotent Consumer is closely connected to Webhook Consumer, Webhook Deduplication, and Idempotent Processing. For Idempotent Consumer, a missing response should remain uncertain until status lookup or reconciliation confirms whether the original operation executed.

Operational review of Idempotent Consumer should separate successful recovery from repeated attempts that only increase latency or load. Metrics for Idempotent Consumer should separate first-attempt success, recovered operations, exhausted attempts, duplicate prevention, and added latency.

A Idempotent Consumer decision should use documented method semantics and provider error classes rather than message text alone. Manual intervention for Idempotent Consumer should begin only after automated status checks cannot determine a safe final outcome.