Webhooks explained: what they are and how to use them safely
A webhook is a message one system sends another the moment something happens. How webhooks work, how they differ from polling, and how to receive them.
By Sohail Hussain21 November 20265 min read
A webhook is an automatic message that one system sends to another the moment something happens: a payment succeeds, a customer replies on WhatsApp, a form is submitted, an invoice is created. Technically, it is an HTTP POST request, usually carrying JSON, sent to a web address you registered with the sending system. Instead of your software asking "anything new?" every few minutes, the other system tells it straight away. Webhooks are easy to receive and easy to receive badly. The safe pattern is to verify the sender, reply quickly, do the work in the background and expect the same event more than once.
Receiving and sending webhooks is everyday work in our APIs and integrations service. This guide explains how they work, what goes wrong, and the checks that keep them trustworthy.
How does a webhook work?
Five steps, every time:
- You register a URL with the sending system, such as Stripe, Razorpay, Meta's WhatsApp platform or Zoho Books, and choose which events you want.
- Something happens in that system: a payment is captured, a message arrives.
- The sender posts a payload to your URL. It describes the event: its type, an ID, a time, and either the object itself or a reference to it. Headers carry a signature that proves who sent it.
- Your endpoint replies with a 2xx status code, meaning "received". Anything else, including a timeout or a redirect, counts as a failure, and the sender may try again later.
- Your system acts on it: marks the order paid, creates a lead, notifies someone.
To see what real payloads look like, our webhook payload formatter includes samples from Stripe, Razorpay and WhatsApp, and validates any JSON you paste in.
How is a webhook different from polling an API?
| Polling | Webhook | |
|---|---|---|
| Who starts it | Your system asks on a schedule | The other system tells you |
| Delay | Up to the polling interval, often minutes | Usually seconds |
| Load | Constant requests, mostly finding nothing | One request per event |
| API limits | Every check uses part of your allowance | Do not count against your calls |
| If your side is down | You catch up on the next check | Events may be lost if the sender stops retrying |
Webhooks are faster and cheaper, but they are notifications, not the record. The sending system's API is the record. Good integrations use webhooks for speed and a periodic check against the API to catch anything that was missed. API integration explained covers the wider picture.
What can go wrong with webhooks?
Your endpoint is down or slow. Senders retry, but each one differently:
| Sender | How fast you must reply | Automatic retries | Signature header |
|---|---|---|---|
| Stripe | Return 2xx before any complex logic | Up to three days with increasing gaps in live mode; three times over a few hours in a sandbox | Stripe-Signature |
| GitHub | Within 10 seconds | None; you redeliver missed ones yourself | X-Hub-Signature-256 |
| Zoho Books | 5-second connection and 10-second read timeout | Five by default, configurable up to 20 | X-Zoho-Webhook-Signature |
Sources, as of October 2026: Stripe's webhook documentation, GitHub's webhook best practices and the Zoho Books webhook help.
The same event arrives twice. Retries mean duplicates. If your handler creates an invoice every time it sees "order paid", a retry creates a second invoice.
Events arrive out of order. Stripe says plainly that it does not guarantee order. "Subscription updated" can arrive before "subscription created".
Someone fakes one. Your webhook URL is just an address. Without signature checks, anyone who finds it can post a fake "payment succeeded".
A redirect breaks delivery. Stripe and Zoho Books both treat a redirect as a failure. Registering http:// when your site redirects to https://, or leaving off a trailing slash your server adds, is enough to fail every delivery.
How do you receive webhooks safely?
Verify the signature against the raw body. Most senders sign each payload with a secret you share, using HMAC with SHA-256. Check it before parsing the JSON, because parsing and re-serialising changes the bytes. Use the sender's own library where one exists. Stripe signs a timestamp together with the body, and Zoho Books encodes its signature differently, so the details vary. The core check, for a sender that sends a hex signature of the body, looks like this in Node.js:
import crypto from "node:crypto";
// rawBody: the exact bytes received, before any JSON parsing
// receivedHex: the signature from the header, with any prefix such as "sha256=" removed
export function isValidSignature(rawBody, receivedHex, secret) {
const expected = crypto.createHmac("sha256", secret).update(rawBody).digest();
const received = Buffer.from(receivedHex || "", "hex");
return received.length === expected.length && crypto.timingSafeEqual(received, expected);
}
Reply first, work later. Save the event, return 200, and process it from a queue. Slow work before replying causes timeouts, and timeouts cause retries.
Record every event ID and skip ones you have already processed.
Do not trust order or contents for anything important. When it matters, use the event as a prompt to fetch the current state from the sender's API.
Use HTTPS, exempt the route from CSRF checks, and never redirect it.
Keep a log of raw payloads for a limited period, mindful of the personal data inside them.
Where do webhooks show up in a typical business?
More places than most owners realise:
- Payments: payment captured, refund issued, subscription renewed or failed.
- WhatsApp: incoming messages and delivery statuses. How to integrate the WhatsApp Business API covers that setup.
- Forms and CRMs: new lead, deal moved to "won". See connecting website forms to your CRM.
- E-commerce: order created, shipped, returned.
- Accounting: invoice created, payment recorded.
Each one is a chance to remove a manual step between two tools you already pay for, which is often cheaper than replacing either; custom software vs off-the-shelf explains when that stops being true.
How do you test webhooks before going live?
Use the sender's test mode. Stripe's CLI, for example, can forward test events to your laptop with stripe listen --forward-to localhost:4242/webhook. For other senders, a tunnelling tool gives your local machine a temporary public HTTPS address.
Then test the unhappy paths, not just the happy one: send the same event twice, send one with a wrong signature, make your endpoint return a 500 and watch the retry arrive, and send events out of order. Once live, alert someone if no webhooks arrive during a period when some always should. Why integrations break covers that monitoring in more depth, and it is the next thing to read once your first webhook is working.
Was this guide useful?