Preventing Webhook Timeouts With Immediate Acknowledgment

A provider sends the receiving service an HTTP request with a webhook event, such as an order or account change. The provider expects a response before a deadline. If the receiver waits for slow work, such as updating business records, to finish before replying, the provider can time out and mark the delivery as failed.

To avoid a timeout, the receiver checks the request, saves the event so it remains available if the receiver stops, and returns the success response the provider expects. A background worker, a separate process that handles the longer task, then does the business work. The response tells the provider that the receiver has accepted responsibility for the event; it does not mean the task is complete.

Why the response deadline matters

A webhook sender measures how long it takes to receive a response. If the receiver is still calling another service, updating records, or waiting for a job when the deadline passes, the provider can treat the delivery as failed even if the receiver eventually finishes.

Providers set different deadlines. Slack’s Events API expects a successful response within three seconds and documents retries after failed attempts. Shopify treats a delivery as failed if it does not receive a response within five seconds. GitHub.com documents a ten-second deadline. These values apply to the specific products and documentation cited, not to webhooks generally. Check the provider’s current delivery requirements before setting the receiver’s response target. See the Slack Events API, Shopify webhook troubleshooting guidance, and GitHub’s webhook delivery guidance.

A timeout can trigger another delivery attempt. That adds load and can result in the receiver seeing the same event more than once. A retry also does not guarantee eventual delivery: providers use different retry policies, and some stop retrying after a limit.

Accept the event before doing the slow work

The receiver should handle the request quickly and save the event before it acknowledges success. A typical flow is:

Provider → receiver → durable storage or queue → success response → background worker → business processing

The receiver first reads the request and makes the minimum checks needed to accept it, such as checking the provider’s signature and confirming that the request has the required structure. It then saves the event in durable storage, such as a database, or places it in a durable queue, a holding area for events waiting to be processed. Durable storage or a durable queue keeps the event available if the receiver stops or a worker fails.

Once the storage has saved the event or the queue has accepted it, the receiver returns the successful HTTP response the provider expects. A background worker can then do slower work, such as calling another API or updating multiple systems. GitHub recommends queueing webhook payloads for asynchronous processing, and Slack advises separating event receipt from longer event handling. AWS Prescriptive Guidance likewise recommends waiting until the event has been durably persisted before acknowledging it.

The order matters. If the receiver sends success before it has stored or enqueued the event, a crash can leave the provider believing the delivery succeeded while the receiver has no copy to process. If the receiver waits for the business task to finish, it keeps the provider waiting and risks a timeout. Durable intake followed by prompt acknowledgment avoids both problems.

Make background processing safe to repeat

A fast acknowledgment reduces timeout failures, but it does not prevent duplicate deliveries or guarantee that later processing will succeed. The provider can retry a delivery, and a worker can fail after accepting an event. The receiver needs separate controls for those cases.

Use an event or delivery identifier that stays the same when the provider retries, so the receiver can recognize duplicate deliveries. Make the worker’s actions idempotent, which means processing the same event again does not repeat an effect that should happen only once. For example, before creating a record, the worker can check whether it already created that record for the same event.

The worker should also record processing outcomes and retry failures that can succeed on another attempt. A dead-letter queue is a separate holding area for messages that repeatedly fail, so an operator can inspect them without blocking other work. Monitor how many events are waiting in the queue and how long processing takes. Also track failures after acknowledgment; the HTTP response alone only shows that the receiver accepted the event. Shopify also warns that webhook delivery is not guaranteed and recommends reconciliation against its API to find missed or mishandled changes.

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