Stripe webhook · Stripe CLI

stripe listen forwarding problems (local)

[ERROR] Failed to POST: Post "http://localhost:3000/api/webhook": dial tcp [::1]:3000: connect: connection refused

What it means

The CLI receives events and forwards them to a local URL. It fails if the dev server isn't running, the port or path is wrong, or your app uses a different secret than the one stripe listen printed.

Common causes

• next dev isn't running, or runs on another port
• Wrong path in --forward-to
• localhost resolves to IPv6 ::1 while the server listens on IPv4
• STRIPE_WEBHOOK_SECRET is the Dashboard secret, not the CLI one

How to fix it

1. Start next dev first, then stripe listen --forward-to localhost:3000/api/stripe/webhook
2. Copy the whsec_ it prints into .env.local and restart next dev
3. Try 127.0.0.1 instead of localhost if you see [::1] connection refused
4. Fire a test with stripe trigger checkout.session.completed

npm run dev
stripe listen --forward-to localhost:3000/api/stripe/webhook
# copy the printed whsec_... into .env.local, restart dev
stripe trigger checkout.session.completed

$ stripe listen --forward-to localhost:3000/api/stripe/webhook
$ stripe listen --print-secret   # the whsec_ to put in .env.local
$ stripe trigger checkout.session.completed

Prompt for Cursor or Claude Code

Set up local Stripe webhook testing for this app. Tell me the exact stripe listen --forward-to command for my webhook route and port, which env var gets the printed whsec_, and which stripe trigger commands cover the events my handler uses.

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