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
| Symptom | Likely cause | Try |
|---|---|---|
| Nothing arrives at all | Wrong URL, event type not subscribed, webhook disabled after failures | Send to an echo endpoint and check the sender's log |
| 404 Not Found | Path typo, trailing slash, wrong HTTP method on your route | Compare the echoed url and method with your route |
| 401 / 403 | Signature check failing, auth middleware on the route | See signatures |
| 400 / 422 | Body parsed with the wrong content type | Check the echoed content-type header and json/form fields |
| 413 | Payload larger than your server allows | Check the echoed data size |
| 5xx | Your handler threw an exception | Your server logs; reproduce with the echoed payload |
| Timeouts | Handler doing slow work before responding | See slow endpoints |
| Duplicate events | Retries after timeouts or errors | Deduplicate by event ID; see retries |
| Redirect (301/302) | HTTP to HTTPS redirect or trailing-slash redirect | Use 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
localhostor 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.