The Goal
A handler is idempotent when running it twice produces the same result as running it once. Since at least once delivery causes duplicates, idempotency is what keeps effects correct.
Idempotency Keys
Give each unit of work a stable key, such as an order id or a hash of the inputs. Before acting, check whether that key has already been processed.
- Record first by inserting the key into a processed table with a unique constraint. A duplicate insert fails, so you skip the work.
- Conditional update that only applies a change if a state column still has the expected value.
Natural Idempotency
Some operations are inherently safe to repeat:
- Set status to shipped is idempotent because the second set changes nothing.
- Increment a counter is not, because each run adds again. Replace it with a write keyed by the job id.
External Side Effects
When a handler calls a third party such as a payment provider, pass an idempotency key to that provider too. Then a retry on your side becomes a no op on theirs rather than a double charge.
Key idea
Use an idempotency key with a unique record or conditional write so a duplicate job run has no extra effect.