What is a webhook: webhook meaning, and why it is the opposite of an API call
A webhook is an HTTP callback: when a defined event happens in one system, that system sends an HTTP POST to a URL you registered in advance, delivering the event data at the moment it occurs rather than waiting to be asked for it. Jeff Lindsay coined the term in 2007, from the programming idea of a hook.
Webhook versus API: pushed, not pulled
This is the distinction every integration conversation turns on.
With a REST API, your system initiates. You decide when to ask, you make the request, you get the current state back. Nothing happens unless you go and look. Learning about changes means polling on a timer, which is either wasteful or slow, and usually both.
With a webhook, their system initiates. You register a URL, they call it when the event fires, and your endpoint is the server for that request. Latency drops to roughly network time and the empty polls disappear.
- Direction. API: you call them. Webhook: they call you.
- Timing. API: whenever you choose. Webhook: the moment the event happens.
- Infrastructure. API: a client is enough. Webhook: a publicly reachable HTTPS endpoint, which is a real operational commitment.
- State. API: current truth on demand. Webhook: a notification about a moment already past.
Most working integrations use both. The webhook says something changed. The API call fetches the authoritative state, which matters because a payload sitting in a retry queue for twenty minutes may already be stale.
How does a webhook work?
The mechanics are ordinary HTTP, which is most of the appeal:
- Registration. You give the source system a URL, usually per event type, in a dashboard or through its API.
- Event. Something happens on their side: a submission completes, a payment settles, a case status changes.
- Delivery. They POST to your URL, typically with a JSON body and custom headers carrying an event id, an event type, a timestamp and a signature.
- Acknowledgement. Your endpoint returns a 2xx status quickly. Anything else, or a timeout, is treated as failure.
- Retry. On failure they queue the event and try again on a backoff schedule.
One implementation rule matters more than the rest: acknowledge first, process second. Verify the signature, write the payload to a queue, return 200, then do the real work asynchronously. Endpoints that make a chain of downstream calls before responding are the ones that time out and trigger duplicate deliveries.
Retries, ordering and idempotency
Nearly every provider offers at least once delivery, not exactly once. If your acknowledgement is lost after you processed the event, the sender cannot distinguish that from a failure, so it sends again. Plan for duplicates as a normal condition rather than an incident.
Idempotency is the defence. RFC 9110 defines a method as idempotent when the intended effect of multiple identical requests matches the effect of a single one, which is why a client may safely retry one after a communication failure. Your handler needs the same property:
- Deduplicate on the event id. Store the ids you have processed and drop anything you have already seen. A unique constraint in the database does this better than an application check, because it holds under concurrency.
- Make the side effects safe to repeat. Upsert rather than insert. Set a status rather than increment a counter.
- Do not rely on order. Concurrent delivery and independent retries mean a status change can arrive before the creation event that caused it. Use the event timestamp and ignore anything older than the state you hold.
- Expect backoff, and eventual disabling. Retry schedules run exponentially over hours or days, and most providers switch an endpoint off after sustained failure. Know that threshold and alert before it.
- Have a reconciliation path. Missed events happen. A scheduled API sweep over the last day's records is the safety net against silent gaps.
How to verify a webhook is genuine
Your endpoint is a public URL that anyone can POST to. Treat every request as untrusted until proven otherwise.
The standard mechanism is an HMAC signature. The provider gives you a shared secret at setup, computes an HMAC (usually SHA-256) over the request body for each delivery, and sends the result in a header. You recompute it and compare.
- Sign the raw bytes. Compute over the exact body as received, before parsing. Re-serialising JSON changes whitespace and key order, and the signature will not match.
- Compare in constant time. A normal string comparison exits early on the first mismatching byte and leaks timing information. Use the constant time compare in your language's crypto library.
- Include a timestamp in the signed payload and check it. Without that, a captured request can be replayed forever. Reject anything outside a tolerance window of a few minutes, and keep clocks synchronised.
- Support two secrets at once. Accepting either the current or previous secret is what makes rotation possible without downtime.
- Do not trust the payload for authorisation. A valid signature proves the message came from the provider. It does not prove the actor named inside it was entitled to anything. Re-check permissions on your side.
Webhook example: a submission that opens a case
A customer finishes a guided capture flow at eleven at night. The platform fires a submission.completed webhook to the insurer's middleware, which verifies the signature, stores the event id, returns 200 and queues the work.
A worker then calls the API for the full case, creates a claim record and assigns it to a handler. If the reviewer later sends a retake request, a second event lands on the same endpoint and updates that record instead of creating another. Duplicates fall harmlessly on the deduplication check.
Push based integration is what moves that case without anyone re-keying it, which is why Venta Capture, a product of VentaVid, exposes webhooks alongside its REST API. The pattern holds whichever platform sits on the other end: verify, acknowledge, queue, reconcile.