Why is my webhook not working? A debugging checklist

The quick answer: first find out whether the problem is the sender or your receiver. Point the sender at an echo endpoint like https://webhook.plus/anything/plus/debug. If the sender's delivery log shows a 200 and the echoed payload, the sender is fine and the problem is in your endpoint.

Symptoms and likely causes

SymptomLikely causeTry
Nothing arrives at allWrong URL, event type not subscribed, webhook disabled after failuresSend to an echo endpoint and check the sender's log
404 Not FoundPath typo, trailing slash, wrong HTTP method on your routeCompare the echoed url and method with your route
401 / 403Signature check failing, auth middleware on the routeSee signatures
400 / 422Body parsed with the wrong content typeCheck the echoed content-type header and json/form fields
413Payload larger than your server allowsCheck the echoed data size
5xxYour handler threw an exceptionYour server logs; reproduce with the echoed payload
TimeoutsHandler doing slow work before respondingSee slow endpoints
Duplicate eventsRetries after timeouts or errorsDeduplicate by event ID; see retries
Redirect (301/302)HTTP to HTTPS redirect or trailing-slash redirectUse the final HTTPS URL; many senders don't follow redirects

How do I replay a payload against my own endpoint?

Copy the payload and headers from the echo (or the sender's log), save the body to a file and send it with curl:

curl -i https://your-app.example/webhooks \
  -H 'content-type: application/json' \
  -H 'X-Event-Type: order.created' \
  --data-binary @payload.json

How do I check the content type is handled?

curl https://webhook.plus/anything/plus/ct -H 'content-type: application/json' -d '{"a":1}'   # json: {"a":1}
curl https://webhook.plus/anything/plus/ct -d 'a=1'                                          # form: {"a":"1"}

If your framework only parses JSON, a form-encoded webhook arrives as an empty object.

Still stuck?

  • Is your endpoint public? Senders can't reach localhost or private networks.
  • Is TLS valid? Expired or self-signed certificates are a common silent failure.
  • Is a firewall or WAF blocking the sender's IP ranges or User-Agent?

Test payloads sent here are recorded, so strip secrets first.