How to Test and Debug Webhooks: A Developer's Guide

Webhooks are how modern services talk to each other — Stripe tells you about a payment, GitHub about a push, Shopify about an order. But when a webhook "isn't working," the failure could be anywhere: the sender, the network, the payload shape, or your handler. Here's a systematic way to debug them.

1. Capture the raw request first

Before touching your code, point the service at a webhook catch URL. This records exactly what the sender delivers — headers, body, method, and content-type. If nothing shows up, the sender isn't delivering (check the service's webhook logs and your endpoint URL). If it does show up, the problem is downstream in your app.

2. Inspect the payload shape

Open the captured request and look at the actual JSON. A surprising number of webhook bugs are simply a field being nested differently than you assumed, or a content-type of application/x-www-form-urlencoded where you expected JSON. Seeing the real structure removes the guesswork.

3. Replay to reproduce

Once you have a captured request, replay it against your development endpoint as many times as you need. This turns an intermittent, hard-to-trigger webhook into a repeatable request you can debug with breakpoints.

4. Forward to multiple services

If several systems need the same webhook, use a relay: one inbound webhook fans out to many destinations, with transforms and retries. This is cleaner than chaining services and gives you a delivery log per destination.

5. Watch for security pitfalls

If you build your own forwarder, be careful: letting users supply destination URLs opens you to SSRF, where an attacker points the destination at internal infrastructure or a cloud metadata endpoint. Always validate the resolved IP against private ranges and re-check on redirects.

With a catch URL, a live inspector, replay, and safe forwarding, webhook debugging goes from guesswork to a quick, repeatable process.