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:

  1. 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.
  2. Something happens in that system: a payment is captured, a message arrives.
  3. 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.
  4. 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.
  5. 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?

PollingWebhook
Who starts itYour system asks on a scheduleThe other system tells you
DelayUp to the polling interval, often minutesUsually seconds
LoadConstant requests, mostly finding nothingOne request per event
API limitsEvery check uses part of your allowanceDo not count against your calls
If your side is downYou catch up on the next checkEvents 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:

SenderHow fast you must replyAutomatic retriesSignature header
StripeReturn 2xx before any complex logicUp to three days with increasing gaps in live mode; three times over a few hours in a sandboxStripe-Signature
GitHubWithin 10 secondsNone; you redeliver missed ones yourselfX-Hub-Signature-256
Zoho Books5-second connection and 10-second read timeoutFive by default, configurable up to 20X-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:

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:

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?

Questions

Frequently asked.

Is a webhook the same as an API?

It is part of one, working in the opposite direction. With an ordinary API call, your system asks another system for something. With a webhook, the other system calls your system when something happens. Most integrations use both: the webhook says an order was paid, and an API call fetches the full, current order.

Do I need a server to receive webhooks?

You need something listening at a public HTTPS address. That can be your web application, a serverless function, or an automation tool such as Zapier, Make or n8n, which give you a webhook address to paste into the sending system. A static website on its own cannot receive webhooks.

What happens if my site is down when a webhook is sent?

It depends on the sender. Stripe retries for up to three days in live mode, Zoho Books retries five times by default, and GitHub does not retry automatically. Anything sent while you were down may never arrive, which is why a periodic check against the sender's API is worth having for anything involving money.

Sohail Hussain

Founder, MSH Technologies

Sohail has designed and built websites, web apps and AI products for over 12 years, for clients from Singapore-based industrial groups to early-stage SaaS startups. He writes about what actually worked.

Keep reading

Related guides.

All posts

Your next move

Like what you see? Tell us about it.

A process that takes too long, a website that undersells you, or an idea ready to take shape. Tell us where you are and we will suggest a useful next step.

India · Working with clients worldwide

Sohail, Founder, replies within 1 working day (Mon–Sat, IST). Free and no obligation.