How Webhook Providers Classify Delivery Failures

When a service sends a webhook, it sends an HTTP request to a URL you control. The provider checks whether it got a response, how long the request took, and which HTTP status code your server returned. It uses those details to decide whether to record the delivery as successful, try again, or stop sending the event.

Providers use different failure rules. A 2xx response usually signals success, but providers set different timeout limits and rules for connection errors and status codes that trigger retries. Knowing the sender’s rules helps you read delivery logs and see when repeated failures could cause it to disable your endpoint.

The response status usually decides success

An HTTP status code is a number the server returns to describe the result of a request. Many providers count any 2xx code as success. Funnel Leasing, for example, accepts any 2xx response and does not check the response body. Under its documented rule, a body that says “error” does not change the delivery result.

Many providers count a non-2xx response as a failed delivery. Their retry rules vary: some retry every non-2xx response, while others stop on certain codes. Safe Infrastructure, for example, retries 5xx responses but stops on 4xx responses. Its documentation says a 4xx response drops the delivery permanently.

A provider’s status-code rules can have exceptions. HubSpot’s documentation, discussed in its community thread, says 4xx responses generally do not trigger retries. The exception is 429 (“Too Many Requests”), which does trigger a retry. A user in the discussion reported seeing retries for 404 responses, which conflicts with the documented rule. Check the provider’s current documentation and delivery records to see how it handles each response code.

A timeout counts as failure even if the server keeps working

A provider sets a deadline for receiving a response. If your server does not respond by then, the provider records a timeout and marks the delivery as failed. Your server might still be handling the request, but a response that arrives after the deadline does not change the recorded attempt to a success.

Providers set different limits. Funnel Leasing documents a five-second timeout. OpenTrain and FeatBit each document a ten-second limit. These limits apply to those providers, not to webhooks in general. Compare your handler’s response time with the sender’s published limit. If your handler regularly takes longer, the provider will record failed deliveries even when the handler eventually finishes.

Connection problems can fail before a status code exists

A provider cannot classify a response by HTTP status if it cannot connect to your server or receive a response. Provider documentation may describe these cases as a “connection error,” “network error,” or “server unavailable.” OpenTrain lists connection errors as delivery failures. FeatBit counts a disrupted connection or unavailable receiving server as a failed request.

Connection failures include a refused connection or a DNS error, which means the sender cannot find or reach the destination. Hookdeck’s retry guidance treats those errors and timeouts as reasons to retry. Provider documentation does not always explain how it classifies each network problem, so check the sender’s error descriptions when diagnosing a failed attempt.

The failure classification determines whether the provider tries again

The provider records whether an attempt failed, then applies its retry rules to decide whether to send it again. It stops retrying when the failure falls outside those rules or when it has used all allowed attempts.

For example, Safe Infrastructure retries 5xx responses and temporary network errors up to two times, but stops on 4xx responses. OpenTrain allows five attempts in total, including the first, then marks the delivery FAILED. It documents delays of 1, 5, 30, and 120 minutes between attempts. Check the provider’s documentation for its status-code rules, attempt limit, and stopping conditions.

Some providers disable an endpoint after repeated failures. OpenTrain disables an endpoint after ten consecutive failed deliveries. Funnel Leasing says too many consecutive failed callbacks deactivate webhooks for that callback URL. If events stop arriving, check the delivery status and endpoint state. A delivery that has used all its attempts and a disabled endpoint are different outcomes.

What I'm building

Delegate 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