Event consumers handle duplicates

Every consumed event can arrive more than once; processing it twice must not change the outcome.

HighChecked by hand

Applies to:
Services that consume events
Rule id:
events.consumers-deduplicate

Why it matters

Brokers deliver at least once. A consumer that crashes after doing the work but before acknowledging the message gets it again, and so do consumers during rebalances, retries and replays. If handling an event twice charges a card twice or ships an order twice, the bug is waiting for the first redelivery.

How to apply it

  • Give every event a stable event id set by the producer, never generated by the consumer.
  • Record processed ids in the same transaction as the side effect (an inbox table keyed by event id), and skip ids you have already seen.
  • Where possible, make the handler naturally idempotent instead: upsert by business key, or apply a state transition only if the current state allows it.
  • Keep the dedup window at least as long as the broker's redelivery and replay horizon.

Example

PaymentCaptured { eventId, orderId } arrives twice. The handler inserts eventId into inbox and marks the order paid in one transaction; the second delivery hits the unique key on inbox.event_id and is acknowledged without doing anything.

References

Checklists with this rule

Related agent skill: idempotency-deduplication