← SDNBrosAll Learn Articles
Home / Learn / Webhook Debugging

How to Debug Webhooks — Step-by-Step Troubleshooting Guide

Webhooks failing silently? This guide walks you through every common failure mode and how to fix it — from timeouts to signature mismatches.

Common Webhook Failures

Timeout

Server takes too long to respond. Most providers wait 5-30s before marking delivery as failed.

4xx

Client errors — bad URL (404), auth failure (401/403), or malformed request (400). Check your endpoint path and auth config.

5xx

Server errors — your code crashed or a dependency is down. Check application logs and error tracking.

HMAC

Signature mismatch — wrong secret, wrong encoding, or computing the hash on the wrong body bytes.

Step-by-Step Debugging Checklist

  1. Check your server logs — look for the incoming request. If there's no log entry, the request never reached your server (firewall, DNS, or wrong URL).
  2. Verify the endpoint URL — confirm the full URL including protocol (https://), path, and port. Trailing slashes matter for some frameworks.
  3. Inspect the payload — use a webhook tester to capture the raw request body, headers, and method. Compare against your provider's docs.
  4. Check request headers — look for Content-Type, signature headers, and custom provider headers. Ensure your parser matches the content type.
  5. Validate the response — return 200 OK quickly. Some providers treat 3xx redirects as failures. Never return HTML error pages.
  6. Test with a manual request — use curl or the webhook tester to send a test payload and verify the endpoint works end-to-end.
  7. Check retry behavior — if the provider retries, you may be processing duplicates. Implement idempotency keys to handle this safely.

Tools for Debugging

SDNBros Webhook Tester

Capture and inspect webhook payloads in real-time. See headers, body, timing, and response codes. Try the Webhook Tester →

Webhook Security Checklist

Manually review signature validation, TLS, replay protection, logging, and rate limits. Open the Security Guide →

Signature Generator

Generate and verify HMAC signatures to confirm your verification logic is correct. Open Signature Tool →

Provider-Specific Debugging Tips

Stripe

Use the Stripe CLI: stripe listen --forward-to localhost:3000/webhook to forward events locally. Check the Dashboard → Developers → Webhooks for delivery logs with full request/response details. Stripe signs with Stripe-Signature header using a whsec_ prefixed secret.

GitHub

Go to Settings → Webhooks → Recent Deliveries to see full request/response pairs. GitHub sends a X-Hub-Signature-256 header. Use X-GitHub-Event to filter event types. Test with the "Redeliver" button on any past delivery.

When to Use a Webhook Proxy

A webhook proxy sits between the provider and your server, giving you inspection, replay, and retry capabilities. Use one when:

SDNBros provides a webhook proxy with built-in monitoring, signature verification, and delivery logs so you can debug issues without guessing. Get started free →

Debug Faster with SDNBros

Stop guessing why webhooks fail. Get real-time delivery logs, payload inspection, and automatic retries.

Start Debugging →