Setting Webhook Response Deadlines to Prevent Failures

When an event occurs, such as a payment update or repository change, one service sends another an HTTP request called a webhook. The receiving service must return an acceptable HTTP response before the sender’s response deadline, the time limit the sender sets for that reply. When the receiver does work that takes longer than the deadline, the sender records the delivery attempt as failed, even if the receiver eventually finishes.

The receiver should acknowledge an event promptly after it has safely accepted responsibility for it, then do slower work separately. Each provider sets rules for its deadline, acceptable response, and retries. The receiver must follow the rules for that webhook. Separating acceptance from processing also matters when a sender retries. The first attempt might already have changed data, so the receiver needs a way to recognize the same event and avoid making the same changes twice.

How processing time turns into a timeout

In a synchronous handler, the code that handles the webhook waits until it finishes the event’s work before responding. It might check the request or update a database. It might also call another service that provides data or performs work. Each step adds time before the response reaches the sender. If handling the event and waiting for other services takes longer than the deadline, the sender does not receive an acceptable response in time.

For example, a handler might update its database and then wait for another service it calls before replying. The sender’s timer keeps running during that wait. If the deadline passes, the sender can mark the attempt as failed even though the database update succeeded. A timeout therefore describes what the sender observed: it did not receive an acceptable response in time. It does not prove that the receiver stopped or that its work failed.

Provider deadlines differ. Slack’s Events API expects a valid response within three seconds. Shopify documents a one-second connection timeout and a five-second timeout for the full request, and requires a 200 response. GitHub recommends a 2xx response within 10 seconds and says it terminates the connection and records a failure when the response arrives too late. These values apply only to the named services and timeout types; they do not establish a general webhook standard. See the Slack Events API, Shopify’s delivery requirements, and GitHub’s webhook best practices.

What the sender does after a missed deadline

The sender treats the delivery attempt as failed if it does not receive the response its contract requires. It might retry the request. It might instead record the failure for manual recovery or take another provider-specific action. Slack documents retries for failed Events API requests, and Shopify documents retries after missing or error responses. GitHub Enterprise Cloud documents that failed deliveries are not automatically redelivered, although an operator can redeliver them manually or with a script. Check the policy for the specific product and webhook type rather than assuming every provider retries.

A retry creates a duplicate-delivery risk. The receiver might complete the event’s work after the sender has already timed out. The sender then retries because it never saw the acknowledgement, and the receiver sees the event again. Shopify warns that network timeouts and retries can produce repeated deliveries and recommends idempotent handling. An operation is idempotent when repeating it has the same effect as doing it once. A receiver can use an event or delivery identifier that stays the same across retries to recognize repeated deliveries and avoid making the same change twice.

Acknowledge promptly, then process the event

The receiver can respond promptly by accepting the event first and handling slower business work separately. It should validate the request, record the event reliably, and return the provider-approved success response. A background worker, code that handles queued work outside the webhook request, can then perform the longer tasks. A queue is a holding place for work that another part of the service will handle later.

The acknowledgement’s meaning must match what the receiver has actually done. If success means “accepted for later processing,” the receiver should record the event before returning success. A response sent before the receiver has safely captured the event risks losing it if the receiver fails before processing begins. GitHub recommends using a queue so the receiver can respond when it gets the webhook and process the payload in the background; Shopify also recommends queuing to handle bursts and meet its response limit.

This design separates two durations: the time needed to accept and acknowledge an event, and the time needed to complete its business effects. The second duration can exceed the provider’s response deadline as long as the receiver has accepted the event according to the contract and can complete it later.

What the webhook contract should define

A useful contract states exactly how the sender measures the deadline. It should say when timing starts, whether connection setup has its own limit, and whether the sender considers the response complete when it receives the headers or the full response. Providers do not describe these boundaries uniformly. Shopify, for example, publishes separate connection and total-request timeouts. The contract should also say what happens when the request body takes time to arrive.

The contract must specify which HTTP status codes, the numbers in the response that indicate its result, count as success and what the acknowledgement means. “Return success” is too vague: GitHub describes a 2xx response, while Shopify requires 200. The contract should also clarify whether the response body matters and whether redirects count as success. Define whether an acknowledgement means the receiver merely received the event, recorded it for later work, or completed the requested business action.

Finally, describe what happens after a timeout, connection failure, or unacceptable status. State whether the sender retries, how many times and when, and how long it keeps failed deliveries. State whether duplicate deliveries are possible and how the receiver should identify them. These details let the receiver set an internal response target below the provider’s limit, monitor late responses, and make retries safe. HTTP defines general status semantics, but RFC 9110 does not establish a universal webhook deadline or retry schedule.

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