Designing a Dead-Letter Queue for Webhooks
A webhook sends an event from one service to another over HTTP. If the receiver cannot handle an event, the sender may…
Categories
Mapping HTTP Status Codes to Webhook Failures
When a service sends a webhook to your endpoint, it sends an HTTP request with an event, such as a payment update or account change. Your endpoint returns an HTTP status code, a number that tells the sender whether the request succeeded, was redirected, or encountered an error. The webhook provider uses that code to decide whether the delivery succeeded.
A reachable endpoint can still produce a failed delivery. The provider evaluates the response it receives, including the status code and whether the endpoint responds within the provider’s time limit. Check the provider’s acceptance rules first, then use the returned status code to identify where to investigate.
What each status-code class tells you
The first digit groups HTTP status codes by outcome. A 2xx signals success, while a 3xx signals redirection. A 4xx signals a client-side error, and a 5xx signals a server-side error. Webhook providers commonly accept a 2xx response as acknowledgment, though the exact accepted codes depend on the provider. For example, Stripe documents acceptance of 2xx responses, while a Nylas community discussion describes a requirement for a 200 response. Check the provider’s current documentation for its specific rule.
| Response | Typical webhook outcome | Next debugging step |
|---|---|---|
| 2xx | The provider treats the response as an acknowledgment when the code meets its requirement. | Confirm the exact code and response time in the delivery record. Then check whether your endpoint completed the intended work. |
| 3xx | A provider that requires 2xx treats the redirect response as unsuccessful. | Inspect the redirect target and update the configured endpoint to the intended destination. Do not assume the provider follows redirects. |
| 4xx | The endpoint rejected the request or considered it invalid. | Check request parsing, required fields, authentication, and signature validation. |
| 5xx | The endpoint or a server in front of it reported a server-side failure. | Check endpoint and server logs for exceptions, unavailable dependencies, or failures from a proxy or gateway. |
The HTTP status-code overview describes these broad classes. The table maps them to common webhook outcomes; provider-specific rules determine whether a particular response counts as successful delivery.
Why a reachable endpoint can still fail
A reachable endpoint is one the provider can contact and get a response from. That does not mean the provider accepts the response as a successful delivery. For example, a server that returns 400 or 500 is reachable, but the provider can still record the event as failed because the response was not an accepted 2xx code.
Timing also matters. If your endpoint does not respond within the provider’s time limit, the provider can mark the delivery failed even when the endpoint eventually processes the request. Compare the provider’s delivery record with your server logs to check whether the endpoint responded, what status code it returned, and when it responded.
A 2xx response confirms that the provider received an acknowledgment. It does not prove that your code completed the business action associated with the event. If the delivery appears successful but the expected change is missing, inspect the event-handling path after the endpoint sends its response. Stripe’s webhook testing documentation covers testing how webhook endpoints respond to deliveries.
Use the status code to narrow the investigation
For a 3xx, check the Location response header, which names the redirect destination, and compare it with the URL configured at the provider. Redirect handling varies, so configure the endpoint at the final destination and verify the provider’s rules instead of relying on a redirect.
For a 4xx, start with the request your endpoint received. A 400 response commonly points to a malformed or rejected payload; a 401 can indicate that authentication or signature verification failed. Compare the received body and headers with what your validation code expects. A valid event can still receive a 4xx if the endpoint’s validation logic rejects it.
For a 5xx, inspect the endpoint’s error logs at the time of the delivery. Look for an exception in the handler, a failed database or service call, or an error from a gateway or another server in front of the endpoint. If the application log shows no request, check the logs for the server or proxy that sits in front of it.
For a 2xx paired with a failed-delivery label, compare the provider’s record with the endpoint’s logs. Confirm that the recorded attempt returned the code the provider accepts and that the endpoint responded before the provider’s time limit. Then check whether the handler completed the expected work after acknowledging the request.
What I'm buildingDelegate tasks. Get software.
Give Vroni a GitHub issue, bug report, spec, or rough idea. It reads the repo, plans the change, writes code, runs checks, and works toward a review-ready pull request.
Take a look at vroni.com