A webhook is a way for a system to push an event notification to your application as soon as something happens—payment captured, order created, form submitted—by sending an HTTP request to a URL you register. Instead of asking “anything new?” every minute, your endpoint is told “this just happened.”
Webhooks are one of the most useful tools in modern API integration because they reduce latency and polling load. They also demand stricter operational discipline: your URL must be online, authenticated, and ready for duplicates.
How webhooks differ from ordinary API calls
With a normal API call, your software initiates the request. With a webhook, the remote system initiates a request to you when its event fires. You still use APIs afterward—often to fetch full details or write to another system—but the trigger is push-based.
See API vs webhook for a fuller comparison.
Anatomy of a webhook flow
Webhook handling flow
- Business event occurs in source system
- Source POSTs a signed payload to your URL
- Your endpoint verifies authenticity
- You acknowledge quickly (2xx response)
- Background job processes the event safely
Security and reliability essentials
- Verify signatures or secrets so attackers cannot forge events
- Respond quickly; do heavy work asynchronously
- Design for duplicates (at-least-once delivery is common)
- Log payloads and processing outcomes with correlation IDs
- Provide a replay path when downstream APIs were down
- Use HTTPS only; reject unsigned or stale timestamps when the vendor supports them
When webhooks are unavailable
Some systems only offer polling APIs. In that case, scheduled synchronisation and careful change detection substitute for push events. Middleware often wraps either style behind one operational model so operators see one queue and one exception path.
Local development and tunnels
Developers often expose a temporary HTTPS URL to receive vendor webhooks during build. Production endpoints should be stable, authenticated, and rate-aware. Never leave debug endpoints open to the world, and never reuse development secrets in production.
Ordering and delayed events
Events can arrive out of order (update before create) or arrive twice. Design handlers to be resilient: fetch authoritative state via API when needed instead of assuming perfect event sequence. Idempotent processing keys turn duplicates into no-ops.
Webhook catalogues
Maintain a list of subscribed events, target URLs, secrets rotation dates, and owners. When someone leaves the team, webhook knowledge should not leave with them. Include which environment (sandbox vs production) each subscription belongs to—mixed environments are a classic outage cause.
A concrete example
An ecommerce platform fires order.paid. Your endpoint verifies the signature, returns 200 immediately, and enqueues a job. The job calls the platform API for full line items, maps tax and SKUs, then posts an invoice to accounting. If accounting is down, the job retries; if the item code is unknown, the message goes to quarantine for a human—not into an infinite retry storm.
FAQ
Why did we miss events during downtime?
Many vendors retry for a limited window. If your endpoint was down too long, you need reconciliation jobs to catch up via API polls. Do not assume webhooks alone are a complete backup strategy.
Are webhook payloads always complete?
No. Some vendors send a thin event (“invoice updated”) and expect you to fetch details. Always check whether the payload is authoritative or only a trigger.
How do we stop fake webhooks?
Require signature verification (or a shared secret header), reject unsigned requests, and restrict network access where possible. Treat an open webhook URL like an open write API.
Should every integration use webhooks?
Prefer them when near-real-time reaction matters and delivery is signed and documented. Prefer schedules when webhooks are missing, flaky, or when bulk reconciliation is the real job.
What belongs in middleware vs the webhook endpoint?
Keep the public endpoint thin: verify, acknowledge, enqueue. Put mapping, multi-step orchestration, and retries in a worker or middleware pipeline.
Related concepts
Comparison: API vs webhook. Request basics: how an API works. Hub runtime: how middleware works. Ongoing sync: what is data synchronization.