Stripe webhook · Stripe Dashboard

Timed out / not returning 2xx fast

Webhook delivery failed: Timed out connecting to remote host

What it means

Stripe expects a 2xx quickly. If your handler sends emails, calls other APIs or waits on a cold database before answering, the request can time out (around 10 seconds or more counts as a failure) and Stripe retries it, which also causes duplicates.

Common causes

• Sending email or calling third-party APIs inside the handler
• Cold start plus a slow database connection
• Serverless function timeout on your host
• Awaiting work that isn't needed to acknowledge the event

How to fix it

1. Verify the signature, do the minimal DB write, return 200
2. Move slow work to a queue or background job (or after() in Next.js)
3. Keep the handler idempotent because retries will come

import { after } from "next/server";

await recordEvent(event);            // fast, idempotent DB write
after(() => sendReceiptEmail(event)); // runs after the response
return Response.json({ received: true });

$ stripe listen --forward-to localhost:3000/api/stripe/webhook
# put the whsec_... it prints in .env.local, then restart npm run dev
$ stripe trigger checkout.session.completed

Prompt for Cursor or Claude Code

My Stripe webhook times out. Profile src/app/api/stripe/webhook/route.ts: keep signature verification and the minimal idempotent DB write, then return 200. Move emails and third-party calls out of the request path (after() or a queue). Don't change what gets written.

Not quite your error? Paste yours into the free VibeBoot Doctor or browse the Stripe webhook fixer.