DM
Technical reference

Webhooks Cheatsheet

Receive external events safely and reliably

Must Know

Verify Signature

Verify the raw request body before parsing.

expected = HMAC_SHA256(secret, timestamp + '.' + rawBody)
secureCompare(expected, signature)
reject old timestamps

Acknowledge Quickly

Do not make providers wait for slow business logic.

verify -> persist event -> return 2xx
                 -> process asynchronously

Important Patterns

Idempotent Consumer

Provider event IDs prevent duplicate side effects.

INSERT INTO webhook_events (provider, event_id)
VALUES (?, ?)
ON CONFLICT DO NOTHING

Event State Machine

Events can arrive late or out of order.

payment.pending -> payment.succeeded
payment.pending -> payment.failed

ignore impossible or stale transitions

Useful Recipes

Retry Policy

retry transient failures
exponential backoff + jitter
max attempts
move poison events to DLQ
manual replay tooling

Event Log

Keep enough metadata to debug and replay safely.

provider
event_id
type
received_at
signature_valid
processing_status
attempts
last_error

Pitfalls & Production

Never Trust Payload Alone

A valid event still needs business authorization checks.

verify signature
fetch sensitive resource from provider when needed
validate account/tenant IDs

Secret Rotation

Plan rotation before an emergency.

accept current + next secret during rotation
measure old-secret traffic
remove old secret after provider update