majiayu000 /stripe-local-dev
Ensure Stripe webhooks work in local development by auto-syncing ephemeral secrets.
The Problem
Stripe CLI generates a new webhook secret every time stripe listen starts. If your dev script auto-starts the listener but doesn't sync the secret, you get:
Webhook error: signature verification failed
No signatures found matching the expected signature for payload
The Solution Pattern
Auto-start requires auto-sync. Use dev-stripe.sh:
- Extract secret via
stripe listen --print-secret - Sync to environment (Convex env OR .env.local)
- THEN start forwarding
Architecture Decision
| Webhook Location | Secret Sync Target | Restart? | Recommendation |
|---|---|---|---|
Convex HTTP (convex/http.ts) |
npx convex env set |
No | Best |
| Next.js API Route | .env.local |
Yes | Requires orchestration |
Prefer Convex HTTP webhooks - secret sync is instant, no restart needed.
Implementation
Option A: Convex HTTP Webhooks (Recommended)
Copy script:
cp ~/.claude/skills/stripe-local-dev/scripts/dev-stripe-convex.sh scripts/dev-stripe.sh
chmod +x scripts/dev-stripe.sh
Update package.json:
"stripe:listen": "./scripts/dev-stripe.sh"
Option B: Next.js API Webhooks
Copy script:
cp ~/.claude/skills/stripe-local-dev/scripts/dev-stripe-nextjs.sh scripts/dev-stripe.sh
chmod +x scripts/dev-stripe.sh
Update package.json:
"stripe:listen": "./scripts/dev-stripe.sh"
Note: Next.js needs restart to pick up env changes. The script warns about this.
Verification
After setup, run:
pnpm dev
# Then in another terminal:
stripe trigger checkout.session.completed
# Check logs for 200 response, not 400
Quick Diagnostics
| Symptom | Cause | Fix |
|---|---|---|
| All webhooks return 400 | Stale secret | Restart pnpm dev or run sync script |
| "signature verification failed" | Secret mismatch | Check CLI output matches env |
| Works once, fails after restart | No auto-sync | Add dev-stripe.sh script |
| CLI shows delivered, app shows error | Wrong env target | Check sync target (Convex vs .env.local) |
Related Skills
/check-stripe- Audit Stripe integration/stripe-health- Webhook health diagnostics/stripe-audit- Comprehensive Stripe audit