How to Debug Webhooks Easily
Webhooks are simple in theory and maddening in practice. This guide walks you through the quickest way to isolate and fix webhook problems, without guesswork.
Start debugging now →What is a webhook?
A webhook is an HTTP request that one service sends to another when something happens. Stripe fires a webhook when a payment succeeds. GitHub fires one when someone pushes code. Shopify fires one when an order is placed. Unlike an API call that you make, a webhook is a call that arrives — and you need a public URL ready to receive it.
Common webhook problems
- "It never arrives." Your endpoint is behind a firewall, uses a self-signed cert, returns a non-2xx, or the sender's retry policy already gave up.
- "It arrives but the body is empty." A middleware ate it, content-type was wrong, or a proxy stripped it.
- "Signature verification fails." Your framework parsed the body before verification, or you're using the wrong secret for the environment.
- "It works locally but not in production." Different tunnels (
ngrok, Stripe CLI), different secrets, different proxies in front. - "I can't tell what's being sent." No visibility into headers or body means you're guessing.
Step-by-step debugging guide
Step 1 — Get a public URL you control
Open the webhook debugger and click Generate Webhook URL. You'll get a unique endpoint that captures everything sent to it. This is your "ground truth" — anything that hits it is what the sender actually sent.
Step 2 — Point the sender at that URL
In the sender's dashboard (or config file), replace your real endpoint with the debugger URL temporarily. Fire a test event.
Step 3 — Inspect the request
You'll see the request appear live, with:
- Method — POST / PUT / etc.
- Headers — including authorization, signatures, content-type.
- Query string — if any.
- Body — pretty-printed JSON or raw text.
This tells you exactly what the sender is producing. If something's missing, the problem is on the sender's side or in transit.
Step 4 — Compare with what your app receives
Now send the same event to your own endpoint (or replay it). Log what your app sees. If they don't match, the problem is in your stack: a middleware, a reverse proxy, a WAF, a serverless function's body-parsing quirk.
Step 5 — Fix and replay
Use the Replay Last button to re-send the exact same request as many times as you need while iterating on the fix. No need to re-trigger the event from the source.
Why visibility matters
Most "weird" webhook bugs aren't really weird — they're invisible. You can't debug what you can't see. The moment you can inspect the raw request in real time, 90% of webhook problems become embarrassingly obvious: a typo in a header name, a content-type mismatch, a body that's been re-encoded by a proxy.