Chapter 59: Design Notification System

1. Requirements

Functional Requirements

Non-Functional Requirements

Capacity Estimates

2. High-Level Design

Component Responsibilities

3. Notification Flow

Flow Steps Detailed

Message Schema (Queue)

4. Priority & Rate Limiting

Priority Levels

Rate Limiting Strategy

Priority Queue Implementation (Kafka)

Rate Limiting Pseudocode (Redis Token Bucket)

def check_user_rate_limit(user_id, channel, priority):
    if priority == "P0":
        return True  # P0 bypasses user rate limits

    key = f"rate_limit:{user_id}:{channel}:{priority}"
    limit = 100 if priority == "P1" else 10  # per hour
    window = 3600  # 1 hour in seconds

    current = redis.get(key) or 0
    if current >= limit:
        return False  # Rate limited

    redis.incr(key)
    redis.expire(key, window)
    return True

5. Channel Routing

Channel Router Specifications

Push Notification Flow (APNs/FCM)

SMS Router Logic

Email Router Logic

Provider Failover Decision Tree

def send_notification(channel, payload):
    providers = get_providers(channel)  # [primary, secondary]

    for provider in providers:
        if is_rate_limited(provider):
            continue  # Try next provider

        try:
            response = provider.send(payload)
            if response.status == 200:
                log_delivery(provider, "SENT", response.msg_id)
                return SUCCESS
            elif response.status in [429, 503]:  # Transient error
                log_delivery(provider, "RETRY", response.msg_id)
                continue  # Failover to next provider
            else:  # 4xx error (bad request, invalid token)
                log_delivery(provider, "FAILED", response.error)
                return FAILURE
        except TimeoutException:
            log_delivery(provider, "TIMEOUT", None)
            continue  # Try next provider

    return FAILURE  # All providers exhausted

6. Template Engine

Template Structure

Localization Strategy

Channel-Specific Formatting

Template Rendering Pseudocode

def render_template(template_id, params, locale, channel):
    # 1. Load template with locale fallback
    template = load_template(template_id, locale, channel)
    if not template:
        template = load_template(template_id, "en", channel)  # Fallback

    # 2. Validate required parameters
    for var in template.required_variables:
        if var not in params:
            params[var] = template.fallback.get(var, "")

    # 3. Render subject and body
    subject = render_string(template.subject, params, locale)
    body = render_string(template.body, params, locale)

    # 4. Apply channel-specific formatting
    if channel == "push":
        subject = truncate(subject, 65)
        body = truncate(body, 240)
    elif channel == "sms":
        body = strip_html(body)
        body = shorten_urls(body)
        if len(body) > 160:
            body = segment_sms(body)  # Split into parts
    elif channel == "email":
        body = inline_css(body)  # For email clients
        body = add_tracking_pixels(body)
        body += render_unsubscribe_link(params.user_id)

    return {
        "subject": subject,
        "body": body,
        "metadata": template.metadata
    }

Template Caching Strategy

7. User Preferences

Preference Schema (DynamoDB)

Preference Check Logic

Preference Management API

Quiet Hours Implementation

def is_quiet_hours(user_prefs, current_time):
    if not user_prefs.quiet_hours.enabled:
        return False

    # Convert current_time to user's timezone
    user_tz = pytz.timezone(user_prefs.quiet_hours.timezone)
    local_time = current_time.astimezone(user_tz)

    start = parse_time(user_prefs.quiet_hours.start)  # "22:00" → 22
    end = parse_time(user_prefs.quiet_hours.end)      # "08:00" → 8

    current_hour = local_time.hour

    if start < end:  # e.g., 08:00 - 18:00
        return current_hour >= start and current_hour < end
    else:  # Wraps midnight, e.g., 22:00 - 08:00
        return current_hour >= start or current_hour < end

Frequency Cap Tracking (Redis)

def check_frequency_cap(user_id, channel, priority):
    if priority in ["P0", "P1"]:
        return True  # No cap for high priority

    today = date.today().isoformat()  # "2026-05-12"
    key = f"freq_cap:{user_id}:{channel}:{today}"

    count = redis.get(key) or 0
    cap = get_user_preference(user_id).frequency_cap[channel]

    if count >= cap:
        return False  # Cap exceeded

    redis.incr(key)
    redis.expire(key, 86400)  # Expire at end of day
    return True

8. Deduplication

Deduplication Strategy

Idempotency Key Sources

Deduplication Pseudocode

def check_deduplication(user_id, notification_type, idempotency_key, channel):
    # 1. Compute dedup key
    dedup_key = f"dedup:{user_id}:{notification_type}:{idempotency_key}"

    # 2. Check if already sent within window
    exists = redis.get(dedup_key)
    if exists:
        log_metric("notification.deduplicated", {
            "user_id": user_id,
            "type": notification_type,
            "original_id": exists
        })
        return False  # Skip, already sent

    # 3. Mark as sent
    window_seconds = get_dedup_window(notification_type)  # e.g., 900 (15 min)
    redis.set(dedup_key, notification_id, ex=window_seconds)

    return True  # OK to send

Dedup Window by Notification Type

Edge Cases

9. Delivery Tracking

Notification State Machine

Delivery Log Schema (Cassandra)

Retry Policy

Provider Webhook Handling

Retry Logic Pseudocode

def handle_notification(msg):
    try:
        send_to_provider(msg)
        update_state(msg.notification_id, "SENT")
    except TransientError as e:
        if msg.retry_count >= max_retries(msg.priority):
            send_to_dlq(msg)
            update_state(msg.notification_id, "DLQ")
        else:
            backoff = calculate_backoff(msg.retry_count, msg.priority)
            msg.retry_count += 1
            re_enqueue_with_delay(msg, backoff)
            update_state(msg.notification_id, "RETRYING")
    except PermanentError as e:
        update_state(msg.notification_id, "BOUNCED")
        add_to_suppression_list(msg.user_id, msg.channel)

10. Scalability

Scaling Dimensions

Kafka Partitioning Strategy

Provider Rate Limit Handling

Batch Processing for Marketing (P2)

Auto-Scaling Rules (Kubernetes HPA)

Load Testing Results (Target: 10K req/sec)

Interview Callouts

Key Discussion Points

Follow-Up Questions to Expect

Trade-Offs to Discuss

Webhook Security & Reliability Patterns

Signature Verification (HMAC-SHA256)

Signature Verification Pseudocode

// Sender (webhook publisher)
def send_webhook(url, payload, secret):
    body = json.dumps(payload)
    timestamp = int(time.time())
    signed_payload = f"{timestamp}.{body}"
    signature = hmac_sha256(signed_payload, secret)

    headers = {
        "X-Webhook-Signature": signature,
        "X-Webhook-Timestamp": timestamp,
        "Content-Type": "application/json"
    }

    response = requests.post(url, data=body, headers=headers)
    return response

// Receiver (webhook consumer)
def verify_webhook(request, secret):
    # 1. Extract signature and timestamp from headers
    received_signature = request.headers["X-Webhook-Signature"]
    timestamp = int(request.headers["X-Webhook-Timestamp"])
    body = request.body

    # 2. Reject if timestamp > 5 minutes old (replay attack prevention)
    if abs(time.time() - timestamp) > 300:
        return False, "Timestamp too old, possible replay attack"

    # 3. Recompute signature
    signed_payload = f"{timestamp}.{body}"
    expected_signature = hmac_sha256(signed_payload, secret)

    # 4. Compare signatures (constant-time comparison to prevent timing attacks)
    if not hmac.compare_digest(received_signature, expected_signature):
        return False, "Invalid signature"

    return True, "Valid webhook"

Replay Attack Prevention

Retry Strategy (At-Least-Once Delivery)

Do NOT retry: 400 (Bad Request), 401/403 (Auth Error), 404 (Not Found), 410 (Gone) — these are permanent failures.

Idempotency (Preventing Duplicate Processing)

Idempotency Pseudocode

def handle_webhook(event):
    event_id = event["id"]

    # 1. Check if already processed
    if redis.exists(f"processed_event:{event_id}"):
        log.info(f"Duplicate webhook {event_id}, skipping")
        return 200  # Idempotent: return success

    # 2. Process event + mark as processed atomically
    try:
        with db.transaction():
            process_event(event)  # Business logic (update order, send email, etc.)
            db.execute("INSERT INTO processed_events (event_id, processed_at) VALUES (?, ?)",
                       event_id, now())

        # 3. Cache for fast duplicate check (Redis as L1, DB as L2)
        redis.setex(f"processed_event:{event_id}", 86400 * 7, "1")  # 7 day TTL

        return 200
    except Exception as e:
        log.error(f"Failed to process webhook {event_id}: {e}")
        return 500  # Trigger retry

Dead Letter Queue (DLQ) Strategy

Webhook Versioning (Avoiding Breaking Changes)

Real-World Example: Stripe Webhook Security

// Stripe webhook signature verification (Node.js)
const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY);

app.post('/webhooks/stripe', express.raw({type: 'application/json'}), (req, res) => {
    const sig = req.headers['stripe-signature'];
    const endpointSecret = process.env.STRIPE_WEBHOOK_SECRET;

    let event;
    try {
        // Stripe library verifies signature + timestamp automatically
        event = stripe.webhooks.constructEvent(req.body, sig, endpointSecret);
    } catch (err) {
        console.log(`Webhook signature verification failed: ${err.message}`);
        return res.status(400).send(`Webhook Error: ${err.message}`);
    }

    // Check idempotency (Stripe sends event.id)
    if (await isProcessed(event.id)) {
        return res.status(200).send('Duplicate event, already processed');
    }

    // Handle event
    switch (event.type) {
        case 'payment_intent.succeeded':
            await handlePaymentSuccess(event.data.object);
            break;
        case 'payment_intent.failed':
            await handlePaymentFailure(event.data.object);
            break;
        default:
            console.log(`Unhandled event type: ${event.type}`);
    }

    // Mark as processed
    await markProcessed(event.id);

    // Return 200 to acknowledge receipt (prevents retries)
    res.status(200).send('Webhook received');
});

Webhook Reliability Comparison