Idempotency Keys for Notifications
What You'll Learn
You'll learn how to use unique identifiers to guarantee that each notification is delivered exactly once, even when systems retry failed operations.
The Core Problem
In distributed notification systems, network failures, timeouts, and retries are inevitable. When a worker retries sending a notification after a failure, you risk sending the same message twice—annoying users with duplicate push notifications, emails, or SMS messages. Idempotency keys solve this by making operations safely repeatable.
How Idempotency Keys Work
An idempotency key is a unique identifier (often a UUID) attached to each notification request. Before processing a notification, the system checks if it has already seen this key:
- First attempt: Generate key
notif_abc123, store it in a database/cache with status "processing", send notification - Retry after timeout: See key
notif_abc123already exists with status "sent"—skip sending, return success - Result: User receives exactly one notification, even though the system tried twice
Analogy: The Coffee Shop Receipt
Think of an idempotency key like a coffee shop receipt number. If you show receipt #42 and ask "Did I already pay?", the barista checks their log. If #42 is there, they don't charge you again—they just hand you the coffee. Same receipt, same result, no double-charging.
Implementation Details
Store idempotency keys with:
- Key: Unique notification identifier
- Status: pending, sent, failed
- Timestamp: For expiration (clean up old keys after 24-48 hours)
- Result: Delivery receipt or error code
The notification worker queries this store before every send operation. If the key exists and status is "sent", skip processing and return the cached result immediately.
Key Takeaway: Idempotency keys transform notification delivery from an unreliable operation into a safely repeatable one, enabling exactly-once semantics by detecting and preventing duplicate sends through unique request identifiers.