Explaining Webhook Timeouts to New Integrators

When an event occurs, such as a payment update, a service sends a webhook, an HTTP request, to a URL you provide. Your endpoint receives the request and replies over HTTP. A webhook timeout happens when the sending service does not receive an acceptable response before its deadline.

The timeout clock measures how long your endpoint takes to acknowledge the delivery. It does not wait for your business logic to finish. Return a successful response promptly after accepting the event, then handle slower work separately. The deadline depends on the provider, so check the documentation for the service sending the webhook.

What the provider counts as a timeout

The provider measures the time between sending a webhook request and receiving an acceptable response. A successful response commonly uses an HTTP status code, a number that reports the result, in the 2xx range. That range indicates that the request succeeded. If the response arrives after the provider’s deadline, the provider records that delivery attempt as unsuccessful.

Webhook timeout windows vary by provider. GitHub’s documentation gives a 10-second response window. Shopify’s troubleshooting guidance gives a five-second window, while the PayPal Invoicing API documentation gives 30 seconds for that product area. These figures apply to the named services and contexts. Use the deadline documented by your provider.

A timeout means the provider did not receive the expected response before its deadline. It does not prove that your endpoint’s work failed. Your handler might still be running, or it might have finished after the provider stopped waiting.

Why the acknowledgment matters

The response tells the provider whether your endpoint received the notification successfully. If your endpoint does not respond in time, the provider treats the delivery as unsuccessful, and the event may not reach your code as expected. The consequences depend on the provider.

For example, Shopify describes delivery failures as a cause of delayed data reaching an app. The practical goal is to give the provider a clear, timely signal that your endpoint accepted the event. The response does not tell the provider that every follow-up task has finished.

Acknowledgment time and processing time are different

Your endpoint handles two separate jobs: responding to the webhook request and completing the work the event requires. The provider’s deadline applies to the first job. The second might take longer, especially if it involves updating another service or performing other complex work.

Suppose a provider sends an event saying that a record changed. Your endpoint receives the event and accepts it for handling, then returns a successful response. A background worker, a separate part of your service that handles work later, then performs the slower update. The provider’s delivery check concerns the response, not the worker’s completion. Stripe recommends returning a successful status before complex logic, and GitHub recommends acknowledging receipt and processing the payload in the background.

A quick acknowledgment does not mean the business task is complete. The later work can still fail, so keep the delivery response and the outcome of that work distinct in your design and monitoring.

Acknowledge quickly without losing the event

Your endpoint should accept the notification, hand it off for later processing, and return the success status the provider expects as soon as it can. A queue can hold accepted events for later handling, and a background worker can do work that would otherwise keep the provider waiting. Shopify also recommends responding before processing the event.

Do not return success merely to stop the provider’s timer if your endpoint has not accepted the event for handling. Choose a clear handoff point based on your implementation, and make sure your endpoint can respond promptly once it reaches that point while keeping slow downstream work out of the request-response path.

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