🪝 guides

How to Debug Webhooks (Without Guessing)

By HookNimbus Editorial · Reviewed & edited by Franklin Brown ·July 4, 2026

Webhooks Fail Where You Cannot See Them

A webhook is a request you did not send and often cannot reproduce. A provider fires it, your endpoint either handles it or does not, and by the time you check your logs the moment has passed. Most webhook bugs come down to one question you cannot answer from your own logs: what exactly was sent? The fastest way to debug a webhook is to stop guessing and capture the raw request.

Step 1: Capture the Raw Request

Point the provider at a URL you fully control and can inspect. The Webhook Inspector gives you an instant inbox that records every incoming request exactly as it arrives - method, headers, query string, and body - and shows it live. Send a test event from the provider’s dashboard and watch it land.

What you are looking for:

The HTTP method and path - is it the POST you expected?
The Content-Type - application/json, application/x-www-form-urlencoded, and multipart/form-data are parsed very differently by your framework.
Signature and delivery headers - X-Hub-Signature-256, Stripe-Signature, X-Shopify-Hmac-Sha256, and delivery ids you can use to trace a specific event.
The raw body bytes - not your framework’s re-parsed version. This distinction matters enormously for signatures.

Step 2: Read the Payload

Webhook bodies arrive minified. Paste the captured body into the JSON Formatter to pretty-print it and confirm the shape matches what your handler expects. A surprising number of “the webhook is broken” tickets are really “the field moved into a nested object” or “the amount is in cents, not dollars.”

Step 3: Verify the Signature

If the endpoint is public, anyone who learns the URL can POST to it. Providers sign the payload with a shared secret so you can prove authenticity. Signature checks fail for one dominant reason: you signed a re-serialized body instead of the exact bytes received. Frameworks that parse JSON before you read the raw body will reorder keys and change whitespace, which breaks the HMAC.

Use the Signature Verifier to compute the expected signature from the raw body and your secret, and compare it to the header the provider sent. If they do not match with the raw body, the problem is your secret or your body handling - not the provider.

Step 4: Reproduce and Replay

Once you know what a good request looks like, you can iterate quickly. Use the Webhook Tester to send the same payload shape to your own endpoint from the edge and read the response - status code, timing, and body - without waiting for the provider to fire again. Tweak, resend, repeat until your handler returns 200.

The Habits That Prevent Webhook Bugs

Always return 2xx fast. Acknowledge receipt, then process asynchronously. Providers retry on non-2xx, which can cause duplicate processing.
Make handlers idempotent. Use the provider’s delivery id to dedupe - the same event can arrive more than once.
Read the raw body before parsing when you need to verify a signature.
Log the delivery id so you can trace a single event end to end.

Debugging webhooks is not hard once you can see them. Capture first, read second, verify third, replay fourth - and the guessing disappears.

Try the tools from this article

🪝