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