Webhook Delivery & HMAC Signatures

Learning outcomes

• Implement secure webhook delivery pipelines with HMAC signatures
• Manage delivery retries with exponential backoff and jitter

Mental model

Webhooks reverse the traditional HTTP request model by having the server push real-time event notifications to a client-registered HTTP URL. Reliable delivery requires HMAC signature verification to prevent spoofing and exponential retries to handle target receiver downtime.

Theory

• HMAC Signatures: The sender signs the payload text using a secret key (X-Signature: t=17000000,v1=sha256_hash). The receiver recomputes the HMAC hash to verify authenticity.
• Exponential Backoff & Jitter: Failed deliveries retry after increasing delay intervals (2^attempt * base_delay + random_jitter) to avoid thundering herd spikes when client servers recover.

import hmac
import hashlib
import time
import requests

def send_webhook(endpoint_url: str, payload_bytes: bytes, secret_key: str):
    timestamp = str(int(time.time()))
    # Format: t=timestamp.payload_bytes
    signature_payload = f"{timestamp}.".encode('utf-8') + payload_bytes
    signature = hmac.new(
        secret_key.encode('utf-8'),
        signature_payload,
        hashlib.sha256
    ).hexdigest()

    headers = {
        "Content-Type": "application/json",
        "X-Webhook-Signature": f"t={timestamp},v1={signature}",
        "X-Webhook-ID": "evt_100200300",
    }

    # Execute HTTP POST with timeout
    response = requests.post(endpoint_url, data=payload_bytes, headers=headers, timeout=5)
    return response.status_code

Alternatives and trade-offs

• Synchronous Webhook Dispatch: Simple; blocks server worker threads waiting for third-party client endpoints.
• Asynchronous Queue Dispatch: High throughput, isolated failures; requires task queues (Celery/Redis) and webhook event status tracking databases.

Failure modes and misconceptions

1. Replay Attacks: Attackers intercept valid webhook requests and re-send them to the receiver. Remedy: Include timestamp t= in the signature payload and reject webhooks older than 5 minutes.
2. Infinite Retry Storms: Retrying failed webhooks without exponential backoff and jitter overwhelms recovering client servers.

Decision scenario

Sign all outgoing webhook HTTP POST requests with HMAC-SHA256 headers including timestamps, and process deliveries asynchronously using Celery task queues with backoff retries.

Learning outcomes

• Compute and verify HMAC SHA-256 webhook signatures.
• Mitigate webhook replay attacks using timestamp signatures.
• Implement resilient webhook delivery retries with exponential backoff and jitter.

Trade-offs

Asynchronous webhook dispatch guarantees event delivery reliability, but requires managing retry state databases and secret keys for receivers.

Primary sources

• FastAPI Framework Architecture & Dependency Injection Specification — Tiangolo, verified 2026-07-22