Webhook delivery failure: find where delivery stopped
A delivery failure means the sender did not receive an acceptable response. The cause can be endpoint configuration, DNS or TLS, network policy, routing, authentication, timeout, or application failure.
Classify the failure
| Provider result | Investigate |
|---|---|
| DNS or connection error | Hostname, DNS records, port, firewall, and service availability. |
| TLS error | Certificate chain, hostname, protocol support, and expiry. |
| 404 or 405 | Route path, HTTP method, deployment version, and proxy rewrites. |
| 400 or 401 | Payload parsing, signature verification, and credentials. |
| 429 | Rate limits and burst handling. |
| 5xx or timeout | Application errors, capacity, and slow dependencies. |
Diagnosis procedure
- Copy the exact destination URL from the provider delivery configuration.
- Inspect the provider attempt time, error, status, response body, and retry schedule.
- Check whether Hookmetry or your edge logs captured the request.
- If no request arrived, investigate DNS, TLS, firewall, and routing before application code.
- If the request arrived, inspect authentication, parsing, handler latency, and downstream errors.
- Correct the failure and use a new event or safe redelivery to verify the complete path.
A 2xx response is not the final outcome
The provider can report successful delivery while your queue, database, or worker later fails. Track delivery acceptance and business processing as separate states.
Prepare for retries
- Store the provider event ID before applying side effects.
- Make processing idempotent.
- Use exponential backoff for your own dependency retries.
- Alert on sustained failure rate, not one isolated retry.
Verify the fix
Verification requires a provider delivery with an acceptable response and a confirmed downstream outcome for the same event ID.