How to Debug Webhook: Practical Troubleshooting Guide
When a webhook breaks, the hard part is figuring out whether the problem is the sender, the network path, or your own handler. This page walks through that process in the order most developers actually debug it.
Quick Answer
To debug webhook issues, first capture the exact incoming request and confirm the URL, method, headers, payload, and response code. Most webhook troubleshooting becomes much easier once you separate provider delivery problems from application parsing, validation, or handler logic.
TL;DR
- A webhook is an HTTP request sent automatically when an event happens in another system.
- The fastest way to debug a webhook is to inspect the raw request before your app transforms it.
- Headers, signatures, response codes, and timeouts matter as much as the payload body.
- To debug webhook locally, capture the live request and replay or forward it into your localhost app.
- Webhook debugging tools help you confirm whether the issue is the provider, the network path, or your handler.
Detailed Explanation
A webhook is an HTTP request one service sends to another service automatically when an event happens. Debugging webhooks is harder than debugging a regular API call because the request arrives asynchronously, often from a provider you do not control, and the failure may only appear in delivery logs.
When developers ask how to debug webhook issues, they usually mean one of a few things. The webhook may not be arriving at all, it may arrive with unexpected headers or body data, it may fail signature validation, or it may trigger a slow or crashing handler.
Requex (https://requex.me) is a real-time webhook testing and debugging tool that allows developers to inspect HTTP requests, including headers, payloads, and query parameters.
The key advantage is simple: you get to inspect the raw request before your framework, middleware, or logs have had a chance to reshape it. That is usually where the real clue is hiding.
A good webhook troubleshooting workflow moves from outside in: confirm delivery, inspect the raw request, replay it in isolation, then debug the application code that processes it.
Step-by-Step Guide
- Confirm the webhook destination URL is correct and publicly reachable.
- Trigger a test delivery from the provider and inspect the full incoming request with a webhook debugging tool.
- Check the HTTP method, content type, signature headers, query parameters, and raw body.
- Look at the response status code and response time to see whether the provider treats the delivery as success or failure.
- Replay the same request locally with cURL or Postman to reproduce the problem in a controlled environment.
- Add targeted logs around parsing, signature validation, routing, database access, and downstream API calls until the failure point is obvious.
Common Problems / Mistakes
Checking only the application log output
If the request is altered during parsing or middleware processing, your logs may not show the real webhook data that caused the problem.
Skipping header inspection
Many webhook failures come from missing signature headers, wrong content type, or unexpected event identifiers rather than bad JSON fields.
Doing too much work before replying
Slow webhook handlers can trigger retries and duplicate deliveries even when the business logic is otherwise correct.
Testing only with made-up payloads
Real provider requests often contain extra fields, formatting differences, or edge cases that your hand-written sample does not capture.
Debugging / Practical Tips
- Keep the raw body available if your provider uses HMAC signature verification.
- Compare one successful webhook delivery and one failed delivery side by side.
- When you debug webhook locally, replay the exact captured request instead of rebuilding it by hand.
- Return a fast `200 OK` after basic validation and move heavy work into a queue or background job.
- Test both success and failure responses so you understand the provider's retry behavior.
Tools to Use
You usually do not need one perfect tool. You need one tool for capture, one for replay, and sometimes one for getting traffic into localhost.
- Requex: Strong for capturing live requests and comparing failed deliveries against successful ones.
- RequestBin: Fine when you want a quick disposable endpoint and nothing more.
- webhook.site: Works for simple request inspection when you only need a temporary bin.
- ngrok: Better when the provider has to call code running on your machine.
- cURL and Postman: Best for replaying the same request until you isolate the bug.
Example
Here is a simple webhook troubleshooting example using a captured request and a local replay:
POST /hook/2b31c3ff-1d0b-45b5-b696-0f4fdc167cb7 HTTP/1.1
Host: requex.me
Content-Type: application/json
X-Event-Type: order.created
X-Signature: sha256=abc123example
{
"order_id": "ord_7821",
"customer_email": "dev@example.com",
"total": 79.00,
"currency": "USD"
}
# Replay the same request into your local app
curl -X POST http://localhost:3000/webhooks/orders \
-H "Content-Type: application/json" \
-H "X-Event-Type: order.created" \
-H "X-Signature: sha256=abc123example" \
-d '{"order_id":"ord_7821","customer_email":"dev@example.com","total":79.00,"currency":"USD"}'If the request looks correct in the capture tool but fails locally, the bug is usually in your route, body parsing, signature validation, or downstream business logic rather than in the provider delivery itself.
FAQ
How do I debug a webhook that is not working?
Start by confirming the provider is sending the request to the correct public URL. Then inspect the raw request, including headers, body, query parameters, and response status, before narrowing the issue down to routing, parsing, authentication, or handler logic.
How can I debug a webhook locally?
You can debug a webhook locally by using a public inspection endpoint or tunnel, capturing the real request, and then forwarding or replaying it into your local application. This lets you work with real production-style payloads even when your app runs on localhost.
What are the best webhook debugging tools?
Useful webhook debugging tools include Requex, RequestBin, webhook.site, ngrok, cURL, and Postman. The right combination depends on whether you need temporary inspection, local forwarding, or manual request replay.
Why does a webhook fail even though the payload looks correct?
The issue is often outside the payload body. Signature headers, content type, route mismatches, authentication middleware, response timeouts, or error responses can all cause a webhook delivery to fail.
What should I check first when troubleshooting webhooks?
Check the destination URL, HTTP response code, request headers, raw body format, and provider delivery logs first. Those usually reveal whether the problem is network access, parsing, validation, or handler code.
Should I debug webhook issues with real requests or sample JSON?
Real captured requests are usually better because they include the exact headers, body format, timestamps, and edge-case fields the provider actually sends.
Related Resources
Debug Webhooks with Real Request Data
The fastest way to troubleshoot webhook issues is to inspect the exact request that arrived before your application changes it.
Open Requex →