How to monitor the webhooks you receive (Stripe, GitHub and others)

Your site can be up while incoming webhooks silently fail. How to monitor a webhook receiver with an API check and a heartbeat, and how to build one that does not lose events.

· 6 min read · By the Spot Downtime team

Stripe tells you a payment succeeded. GitHub tells you a push happened. Your shipping provider tells you a parcel was delivered. All of them do it with a webhook: an HTTP request to a URL on your server. When that URL stops working, nothing visible breaks. Your website loads, your dashboard works, and orders quietly stop being marked as paid.

That makes a webhook receiver one of the easiest things to leave unmonitored and one of the more expensive to lose. Here is how to watch it properly, and how to build it so a short outage does not lose events.

Why a normal uptime check is not enough

A check on your homepage proves your homepage works. A webhook endpoint fails for its own reasons:

  • A deploy changed the route, or a framework upgrade changed how the request body is parsed.
  • A firewall, WAF or bot rule started blocking the provider's IP addresses.
  • The signing secret was rotated at the provider but not on your server, so every request fails verification.
  • The handler got slow, the provider's request timed out, and the provider counted it as a failure.
  • The handler returns 200 but a background worker behind it is dead, so nothing is processed.

Providers retry failed deliveries for a while, but each has its own schedule, and many disable an endpoint after enough consecutive failures. Check how long yours retries and what it does when it gives up. Do not assume it will wait for you.

Build the receiver so it fails safely

Monitoring tells you something broke. These habits decide how much damage it does.

  1. Verify the signature, on the raw body. Providers sign the exact bytes they send. If your framework parses the JSON first and you hash the re-serialized object, the signature will not match. Read the raw body, verify, then parse.
  2. Answer fast, work later. Verify, write the event to a queue or database table, and return 200 within a second or two. Do the slow work in a worker. A handler that sends emails and calls three APIs before responding is a handler that times out.
  3. Be idempotent. Retries mean you will see the same event twice. Store the event id and skip ones you have already processed.
  4. Return the right status. Use 2xx only for events you accepted. Use 400 or 401 for a bad signature, and a 5xx when you want the provider to retry. Returning 200 on an error throws the event away.
  5. Do not rely on ordering. Events can arrive out of order. Fetch the current state from the provider's API when it matters.
ts
export async function POST(req: Request) {
  const raw = await req.text();                       // raw body, not parsed JSON
  if (!verifySignature(raw, req.headers.get("x-signature"))) {
    return new Response("bad signature", { status: 400 });
  }
  const event = JSON.parse(raw);
  await queue.add({ id: event.id, payload: event }); // dedupe on event.id in the worker
  return new Response("ok", { status: 200 });         // answer fast
}

Monitor 1: the endpoint is reachable and healthy

You cannot send a real signed event from a monitor, and you should not try to fake one. Instead, give the receiver a small health route that runs through the same stack as the webhook route and checks what it depends on, such as the queue and the database, and returns 200 with a short JSON body.

Then add an API monitor for it with an assertion on the status code and on a field like queue.ok. The monitor runs from outside your network, so it also catches DNS, certificate and firewall problems that a check from inside never would. If your WAF protects the route, allow the checker through; see the allowlist guide.

Also check the real route

An unsigned request to the real webhook route should be rejected quickly with a 400 or 401. A monitor that expects exactly that status proves the route exists, is reachable and still verifies signatures. If it starts returning 404 or 500, something changed.

Monitor 2: events are actually being processed

A reachable endpoint with a dead worker is still an outage. The strongest signal is the absence of a normal, expected event, and that is what a heartbeat monitor is for. Your worker calls a private URL each time it successfully processes an event. If no call arrives within the interval you chose, you are alerted.

ts
// at the end of the worker, after the event is fully processed
await fetch(process.env.HEARTBEAT_URL!, {
  method: "POST",
  signal: AbortSignal.timeout(5000),
}).catch(() => {}); // never let the ping break the job

This only makes sense when events arrive regularly. Choose the interval from your real traffic: a store with a payment every few minutes can use an hour, a small project that gets a few events a day should use a day or more, and an endpoint that may legitimately see nothing for a week should not use a heartbeat at all. Add a grace period so a quiet stretch does not page you. Heartbeat monitors are available on the Starter and Pro plans. Our guide to setting up a heartbeat monitor walks through it.

For low-traffic endpoints, have a scheduled job send a test event through the provider's test mode once a day. The job's success then pings the heartbeat, which verifies the whole path on a schedule you control.

Monitor 3: the provider side

  • Open the provider's webhook dashboard now and then. Most show recent deliveries, response codes and failures, and let you resend missed events once you have fixed the cause.
  • If the provider has an outage, no endpoint of yours is at fault. Monitoring the services you depend on shows how to be told about it.
  • Turn on the provider's own failure emails and send them to a shared inbox, not one person.

Recovering after an outage

  1. Fix the cause and confirm the health route and an unsigned request behave as expected.
  2. Resend failed events from the provider's dashboard, or fetch them through its events API for the outage window.
  3. Rely on the event-id check so that resending an event you already handled does nothing.
  4. Check the numbers against the source of truth, such as payments in the provider against orders in your database.

Summary

Receive fast and verify properly, make handlers idempotent, then watch two things: that the endpoint answers from the outside, and that events keep being processed. Two small monitors cover both, and either one would have caught the usual webhook failures before a customer wrote to support. For wider API coverage, see our API monitoring guide.

Get new guides by email

Practical posts on monitoring, outages, error fixes and on-call, when they're published. No spam.

Unsubscribe from any email with one click. See our privacy policy.

Keep reading