Webhook

Receiving: Signature Verification

• •Always verify HMAC signature—payload can be forged; don't trust without signature
• •Common pattern: HMAC-SHA256(secret, raw_body) compared to header value
• •Use raw body bytes—parsed JSON may reorder keys, breaking signature
• •Timing-safe comparison—prevent timing attacks on signature check
• •Reject missing or invalid signature with 401—log for investigation

Receiving: Replay Prevention

• •Check timestamp in payload or header—reject if too old (>5 minutes)
• •Combine with signature—timestamp without signature can be forged
• •Store processed event IDs—reject duplicates even within time window
• •Clock skew tolerance: allow 1-2 minutes past—but not hours

Receiving: Idempotency (Critical)

• •Webhooks can arrive multiple times—sender retries on timeout, network issues
• •Use event ID for deduplication—store processed IDs in database/Redis
• •Make handlers idempotent—same event twice should have same effect
• •Idempotency window: keep IDs for 24-72h—balance storage vs protection

Receiving: Fast Response

• •Return 200/202 immediately—process asynchronously in queue
• •Senders timeout (5-30s typical)—slow processing = retry = duplicates
• •Minimal validation before 200—signature check, then queue
• •Background job for actual processing—failures don't affect acknowledgment

Receiving: Error Handling

• •2xx = success, sender won't retry
• •4xx = permanent failure, sender may stop retrying—use for bad signature, unknown event type
• •5xx = temporary failure, sender will retry—use for downstream issues
• •Log full payload on error—helps debugging; redact sensitive fields

Sending: Retry Strategy

• •Exponential backoff: 1min, 5min, 30min, 2h, 8h—then give up or alert
• •Cap retries (5-10 attempts)—don't retry forever
• •Record delivery attempts—show status to user
• •Different retry for 4xx vs 5xx—4xx often means stop retrying

Sending: Signature Generation

• •Include timestamp in signature—prevents replay of captured webhooks
• •Sign raw JSON body—document exact signing algorithm
• •Header format: t=timestamp,v1=signature—allows versioned signatures
• •Provide verification code examples—reduce integration friction

Sending: Timeouts

• •5-10 second timeout—don't wait forever for slow receivers
• •Treat timeout as failure—retry later
• •Don't follow redirects—or limit to 1-2; prevents redirect loops
• •Validate HTTPS certificate—don't skip verification

Event Design

• •Include event type: {"type": "order.created", ...}—receivers filter by type
• •Include timestamp: ISO 8601 with timezone—for ordering and freshness
• •Include full resource or ID—prefer full data; saves receiver a lookup
• •Version events: api_version field—allows breaking changes

Delivery Tracking

• •Log every attempt: URL, status code, response time, response body
• •Dashboard for retry queue—let users see pending/failed deliveries
• •Manual retry button—for stuck webhooks after receiver fix
• •Webhook logs retention: 7-30 days—balance debugging vs storage

Security Checklist

• •HTTPS only—never send webhooks to HTTP endpoints
• •Rotate secrets periodically—support multiple active secrets during rotation
• •IP allowlisting optional—document your IP ranges if offered
• •Don't include secrets in payload—webhook URL should be secret enough
• •Rate limit per endpoint—one slow receiver shouldn't affect others

Common Mistakes

• •No signature verification—anyone can POST fake events to your endpoint
• •Processing before responding—timeout causes retries, duplicate processing
• •No idempotency handling—double charges, duplicate records
• •Trusting event data blindly—always verify by fetching from source API for critical actions