Idempotent Consumer

Overview

What does Idempotent Consumer mean?

An Idempotent Consumer processes a message, webhook, or event so receiving the same logical input multiple times does not create additional business side effects.

How it works in practice

An idempotent consumer reads messages or webhooks without repeating business effects when the same event is delivered again. It stores a durable event identifier or business-state transition and performs deduplication atomically with the intended database change. This is essential because message brokers and webhook providers may redeliver after lost acknowledgments. Consumers should also handle out-of-order events: an older pending notification cannot overwrite a newer verified paid state just because it arrived later.

Limits and common misunderstandings

Acknowledging an event before durable processing may lose updates on crashes; writing a duplicate marker before a failed payment credit can falsely block recovery. Event-level deduplication alone is insufficient if two different event IDs describe the same underlying transfer.

Additional implementation considerations

Safe deduplication should cover both event IDs and financial business keys. A gateway might issue a second event ID for the same underlying transfer after a status transition; consumers must determine whether it updates the known payment or starts a distinct operation. A robust pattern writes the event receipt and intended ledger state in one database transaction, then acknowledges the message. Recovery tests deliberately crash between parsing, committing and acknowledging.

Related glossary terms

Webhook Consumer; Webhook Deduplication; Idempotent Processing