Stripe webhook "timed out": why deliveries fail and how to respond fast enough

Stripe's docs say your endpoint must quickly return a 2xx before any complex logic that could cause a timeout. The webhooks guide doesn't give an exact cutoff in seconds, so don't design around one. Acknowledge first, then do the work.

Typical causes

1. Doing the work inline. Sending emails, calling other APIs, generating PDFs or running slow database writes before you send the response.
2. Cold starts on serverless functions, stacked on top of that inline work.
3. Synchronous handling during spikes. Stripe warns that big bursts (for example, monthly subscription renewals) can overwhelm endpoints that process events synchronously, and recommends an asynchronous queue.
4. Waiting on locks or on a call back to the Stripe API inside the handler.

Fix: verify, enqueue, return 200

app.post('/webhook', express.raw({ type: 'application/json' }), async (req, res) => {
  let event;
  try { event = stripe.webhooks.constructEvent(req.body, req.get('stripe-signature'), secret); }
  catch (e) { return res.status(400).send(e.message); }
  await queue.add(event.type, { id: event.id });   // fast: store it, don't process it
  res.sendStatus(200);
});
// a separate worker processes the queue and de-duplicates on event.id

On serverless platforms you usually can't keep working after you've returned. Hand the event to a real queue (or your platform's background or after-response feature, within its time limits).

What happens to the events that timed out

In live mode, Stripe retries failed deliveries with exponential backoff for up to three days. Sandbox events are retried only three times over a few hours. Retries stop if the endpoint is disabled or deleted. To catch up faster, list missed events with GET /v1/events?delivery_success=false, process them idempotently, and return 2xx when the retries arrive. Manually resending an event doesn't cancel Stripe's automatic retries.

Retries mean duplicates, so see handling duplicate Stripe events.