Course contentsShow
← System Design
Lesson 1711 of 1,91941. Real-World System: Notification SystemFree lesson

Idempotency Keys for Notifications

Using unique identifiers to detect and prevent duplicate notification delivery to end users.

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:

  1. First attempt: Generate key notif_abc123, store it in a database/cache with status "processing", send notification
  2. Retry after timeout: See key notif_abc123 already exists with status "sent"—skip sending, return success
  3. 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.