What is Webhook?
A webhook is a lightweight integration pattern where one system sends an HTTP POST to a pre-registered URL on another system whenever a defined event happens — turning polling into push and enabling near-real-time workflows.
Webhooks invert the integration model. Instead of System B asking System A "anything new?" every minute, System A tells System B the moment something happens. This is the backbone of every modern SaaS integration: Stripe payment_succeeded, GitHub push, Slack message.received, HubSpot contact.created. Webhooks are simple to build wrongly and disciplined to build right — idempotency, retries, signature verification, and replay are non-negotiable.
What it includes
- HTTPS endpoint that accepts POST with JSON payload
- Signature verification (HMAC) so receivers trust the sender
- Idempotency keys so retries do not double-process
- Acknowledgement-on-receive, asynchronous processing on the consumer
- Replay log of recent events for debugging and recovery
- Rate limiting and exponential backoff on the sender
How it works
Define the event taxonomy
List every event the system will emit, with a stable name (resource.action) and payload schema. Versioning starts here.
Build the dispatcher
A queue-backed sender that signs the payload, delivers, retries on failure with exponential backoff, and dead-letters after a configurable maximum.
Build the receiver carefully
Verify signature, check idempotency key, return 2xx fast, push the actual work into a background queue. Slow receivers cause delivery storms.
Document for the consumer
Every event documented with payload example, signature scheme, retry policy, and a sandbox to test against. Test fixtures shipped, not just narrative.
Monitor delivery
Per-endpoint delivery rate, latency, and dead-letter count. Surface failures to the consumer with enough detail to fix.
Frequently asked
Webhook or polling?
Webhook when the event must be acted on quickly and frequency is low-to-medium. Polling when the volume is huge, the consumer is offline often, or the source does not support webhooks.
How do you handle a webhook that fails to deliver?
Retry with exponential backoff (1m, 5m, 30m, 2h, 12h...) up to a configurable limit. After exhausting, dead-letter to a queue the consumer can inspect and replay.
Is a webhook secure?
Only if you verify the signature on every request. Always use HMAC with a shared secret. Reject unsigned or mismatched requests at the edge before any business logic runs.