Software Growth

Webhook

A webhook is an HTTP request your software sends to a customer's URL when an event happens, so they get told instead of having to keep checking.

A webhook flips the usual direction of an API. Instead of a customer's code asking you "did anything change?" every few minutes, you send them a message the moment something does. Stripe describes it this way: after you register an endpoint, Stripe sends data to it in real time when events occur, as an HTTPS request with a JSON payload.

Webhooks vs polling

Polling means the customer calls your API on a schedule and compares results. It is simple, but it wastes requests and is always a little late. Webhooks are event-driven: nothing is sent until there is something to say.

Say a customer polls your API every minute to catch new orders. That is 1,440 calls a day, and most return nothing. With a webhook it is one call per order. For an event that arrives late and asynchronously, such as a bank confirming a payment or a subscription renewal succeeding, webhooks are the natural fit. Stripe uses them for exactly those cases.

What a good webhook system needs

  • Signatures. Stripe signs each request so the receiver can check it came from Stripe and not from someone who guessed the URL. Customers need the raw request body to verify it.
  • Fast acknowledgment. Stripe's guidance is to return a 2xx response quickly, before any heavy processing, so the sender does not time out.
  • Retries. Receivers go down. You need to retry failed deliveries and tell customers that duplicates can happen, so their handler should be safe to run twice.
  • A log. A page where the customer can see recent deliveries, response codes and a "resend" button will cut your support load.
  • Test events. Let people trigger a sample event from a sandbox without creating real data.

Common mistakes

Sending giant payloads that change shape, skipping signatures, and giving no way to replay a missed event. Another is treating delivery order as guaranteed. Design events to carry an ID and a timestamp, and tell customers to fetch the latest state if order matters.

When a small SaaS should care

If you already have an API and customers integrate with Zapier, Make or their own scripts, webhooks are usually the second feature they ask for. They pay off when your events carry money or status: payment succeeded, trial ended, report finished. A first version can be a handful of event types, one signature scheme and a retry queue. Wrap it in your SDK later so developers get a ready-made signature check.

Related terms

Sources

Back to the SaaS glossary