Idempotent Event Handlers: Don't Double-Count Events

Why it exists

Event-driven systems often use message queues to decouple event producers from consumers, as described in event sourcing. In these distributed systems, network issues or service restarts can cause a message queue to deliver the same event more than once. If an event handler isn't prepared for this, it can lead to critical bugs, like charging a customer twice or adding the same item to an order multiple times.

The mental model

An idempotent event handler is like a bouncer with a checklist at a private event. The first time a guest (the event) arrives with a valid ticket (the event ID), the bouncer checks their name off the list and lets them in. If the same guest tries to enter again later, the bouncer sees their name is already checked off and politely turns them away. The final state—the guest is inside—is the same whether they tried to enter once or five times. The handler ensures an event's side effect happens only once.

How it works

To achieve idempotency, a handler must first check if it has already processed a given event before executing its core logic. A common technique is to store the unique IDs of processed events in a persistent store, like a database table or a Redis set. When an event arrives, the handler checks if its ID exists in this store. If it does, the handler ignores the event and simply acknowledges it to the queue. If not, it processes the event, then atomically records the event ID in the store as part of the same transaction.

When to use it

Use idempotent handlers whenever an event triggers an action with side effects in a system with at-least-once message delivery. This is critical for handlers that modify data in a database (like updating a materialized view, as mentioned in event sourcing), call an external API that isn't idempotent itself, or send a notification like an email. Any operation that shouldn't run twice needs this protection.

When not to use it

Idempotency is less critical for operations that are naturally idempotent, such as setting a specific value (e.g., user.status = 'active'). If you have a system that truly guarantees exactly-once processing, which is rare and complex, the overhead may be unnecessary. However, for most distributed architectures that rely on message queues, building idempotent handlers is a defensive best practice.

One canonical example

In an event sourcing system, an OrderConfirmed event with ID evt_123 is published. A handler consumes this to send a confirmation email. Due to a temporary network failure, the queue redelivers evt_123. A non-idempotent handler would send a second email. An idempotent handler would first check a database for evt_123. On the first delivery, it finds nothing, sends the email, and saves evt_123 to its processed_events table. On the second delivery, it finds evt_123 and does nothing, preventing a duplicate email.