stripe-local-dev

Fix Stripe webhook 400 errors in local development. The problem: `stripe listen` generates a new secret each time it starts, but your app uses a stale secret from .env.local. This skill auto-syncs the ephemeral secret before your dev server starts. Auto-invoke when: stripe webhooks return 400, 'signature verification failed', 'No signatures found matching', webhooks not working locally, checkout succeeds but subscription doesn't update, STRIPE_WEBHOOK_SECRET mismatch, setting up stripe listen, configuring pnpm dev with Stripe.

/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