AgentSkillsCN

stripe-local-dev

解决本地开发中的 Stripe Webhook 400 错误。问题在于：每次启动 `stripe listen` 时，都会生成一个新的密钥，而你的应用却在使用 .env.local 中过期的密钥。本技能可在开发服务器启动前自动同步临时密钥，确保 Webhook 正常运行。 适合在以下场景自动触发：Stripe Webhook 返回 400 错误、“签名验证失败”、“未找到匹配的签名”、本地 Webhook 无法正常工作、结账成功但订阅未更新、STRIPE_WEBHOOK_SECRET 不匹配、设置 Stripe Listen、使用 pnpm 配置 Stripe 开发环境。

SKILL.md
--- frontmatter
name: stripe-local-dev
description: |
  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:

code
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:

  1. •Extract secret via stripe listen --print-secret
  2. •Sync to environment (Convex env OR .env.local)
  3. •THEN start forwarding

Architecture Decision

Webhook LocationSecret Sync TargetRestart?Recommendation
Convex HTTP (convex/http.ts)npx convex env setNoBest
Next.js API Route.env.localYesRequires orchestration

Prefer Convex HTTP webhooks - secret sync is instant, no restart needed.

Implementation

Option A: Convex HTTP Webhooks (Recommended)

Copy script:

bash
cp ~/.claude/skills/stripe-local-dev/scripts/dev-stripe-convex.sh scripts/dev-stripe.sh
chmod +x scripts/dev-stripe.sh

Update package.json:

json
"stripe:listen": "./scripts/dev-stripe.sh"

Option B: Next.js API Webhooks

Copy script:

bash
cp ~/.claude/skills/stripe-local-dev/scripts/dev-stripe-nextjs.sh scripts/dev-stripe.sh
chmod +x scripts/dev-stripe.sh

Update package.json:

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:

bash
pnpm dev
# Then in another terminal:
stripe trigger checkout.session.completed
# Check logs for 200 response, not 400

Quick Diagnostics

SymptomCauseFix
All webhooks return 400Stale secretRestart pnpm dev or run sync script
"signature verification failed"Secret mismatchCheck CLI output matches env
Works once, fails after restartNo auto-syncAdd dev-stripe.sh script
CLI shows delivered, app shows errorWrong env targetCheck sync target (Convex vs .env.local)

Related Skills

  • •/check-stripe - Audit Stripe integration
  • •/stripe-health - Webhook health diagnostics
  • •/stripe-audit - Comprehensive Stripe audit