Debug Failed Webhooks
A webhook failed. Now what? Here's how to find out why and fix it.
Step 1: Find the Failed Delivery
Check delivery status via the API or dashboard:
curl "https://hooksniff-api-1046140057667.europe-west1.run.app/v1/webhooks?status=failed&per_page=10" \
-H "Authorization: Bearer hr_live_YOUR_KEY"Step 2: Read the Error Details
Each delivery attempt includes:
curl "https://hooksniff-api-1046140057667.europe-west1.run.app/v1/webhooks/wh_xyz789/attempts" \
-H "Authorization: Bearer hr_live_YOUR_KEY"- HTTP status code (500, 429, timeout, etc.) β
- Response body (the error message from the endpoint) β
- Timing (how long the request took) β
- Error context (DNS failure, TLS error, etc.) β
Common Failure Patterns
500 Internal Server Error
5xx errors β Fix your server. Check logs, database connections, dependencies.
401 Unauthorized
401 Unauthorized β Check if your endpoint expects authentication. Add the required headers.
404 Not Found
404 Not Found β Your endpoint URL is wrong or the route doesn't exist.
Connection Timeout
Timeout β Your endpoint takes too long. Optimize processing or use async pattern.
DNS Failure
DNS failure β Your domain doesn't resolve. Check DNS records.
TLS Error
TLS error β Certificate issue. Renew or fix your SSL certificate.
Step 4: Replay the Delivery
After fixing the issue, replay the failed delivery:
curl -X POST https://hooksniff-api-1046140057667.europe-west1.run.app/v1/webhooks/wh_xyz789/replay \
-H "Authorization: Bearer hr_live_YOUR_KEY"You can also replay from the dashboard with one click.