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.
Event Triggers Webhook Dispatch
Compute HMAC-SHA256 Signature Header
POST HTTP Payload to Client Endpoint
Client verifies Signature with Shared Secret
Retry with Exponential Backoff on Failure
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.
python(25 lines)
1import hmac
2import hashlib
3import time
4import requests
5
6def send_webhook(endpoint_url: str, payload_bytes: bytes, secret_key: str):
7 timestamp = str(int(time.time()))
8 # Format: t=timestamp.payload_bytes
9 signature_payload = f"{timestamp}.".encode('utf-8') + payload_bytes
10 signature = hmac.new(
11 secret_key.encode('utf-8'),
12 signature_payload,
13 hashlib.sha256
14 ).hexdigest()
15
16 headers = {
17 "Content-Type": "application/json",
18 "X-Webhook-Signature": f"t={timestamp},v1={signature}",
19 "X-Webhook-ID": "evt_100200300",
20 }
21
22 # Execute HTTP POST with timeout
23 response = requests.post(endpoint_url, data=payload_bytes, headers=headers, timeout=5)
24 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
- 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. - Infinite Retry Storms: Retrying failed webhooks without exponential backoff and jitter overwhelms recovering client servers.
Reflect before revealing the guide
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.