How Webhooks Work

They call you

A webhook turns the usual arrangement inside out. You hand a provider an address, and when something happens there, a charge succeeds, a subscription lapses, they send the news to you.

No asking, no empty responses, and the news lands seconds after the event instead of at your next poll.

See the catch inside that inversion. You are now running an endpoint on the public internet that another company calls with data your business depends on. Three obligations come with it.

Three obligations

Authenticate whoever is calling. Your address will leak eventually, and anyone who finds it can send you a convincing fake saying a payment succeeded for an order nobody paid for.

Providers solve this by signing every delivery with a secret only the two of you share. Verify that signature against the raw body before you parse anything, and check the timestamp inside it so a captured request cannot be replayed at you next week. An unverified webhook endpoint is an unauthenticated write API into your business logic.

Answer fast, because providers time out slow endpoints and count the timeout as a failure, which triggers retries you never needed.

Write a handler that does almost nothing: check the signature, put the event on an internal queue, return a 200. The real work happens behind that queue.

Expect disorder, because events arrive out of order and more than once whenever a provider retries something it did not hear back about. Your handlers must be safe to run twice, keyed on the event identifier the provider gives you.

post("/webhooks/payments", (req, res) -> {
  byte[] raw = req.rawBody();          // verify the bytes, not the parsed object

  // Your address leaks eventually. Without this, anyone who finds it
  // can post a convincing "payment succeeded" for an unpaid order.
  if (!hmacSha256(raw, SECRET).equals(req.header("X-Signature"))) {
    return res.status(401);
  }
  // And check the timestamp, or a captured request replays next week.
  if (age(req.header("X-Timestamp")).toMinutes() > 5) return res.status(401);

  // Do nothing else. Providers time out slow endpoints and count it
  // as a failure, which triggers retries you never needed.
  queue.send(raw);
  return res.status(200);              // means "durably stored", not "processed"
});

Worked example

Ben integrates Stripe webhooks for a course platform in an afternoon: an Express route parses the event and marks orders paid. It works in test mode, so it ships. Three weeks later a security researcher emails: the endpoint URL appeared in a public client-side bundle, and a hand-crafted POST with a fake payment_intent.succeeded body grants course access with no payment. Nobody malicious found it first, which Ben understands to be luck, not design. The rewrite does it properly: the raw body is checked against the Stripe-Signature header using the webhook signing secret, requests older than 5 minutes are rejected to block replays, and forged requests get a 400 and a security log entry. The researcher's proof-of-concept now bounces, and Ben adds signature verification to the team's integration checklist, one incident too late.