stripe-local-dev

修复本地开发中的Stripe webhook 400错误。问题在于：`stripe listen`每次启动时都会生成一个新的密钥，但您的应用程序使用的是.env.local中过时的密钥。此技能会在您的开发服务器启动前自动同步临时密钥。当以下情况发生时自动调用：stripe webhooks返回400错误，'签名验证失败'，'未找到匹配的签名'，webhooks在本地无法工作，结账成功但订阅未更新，STRIPE_WEBHOOK_SECRET不匹配，在设置stripe listen时，配置带有Stripe的pnpm dev。

/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