ReddRadar
Agent skill
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.
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/stripe-local-dev
SKILL.md
/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
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
Didn't find tool you were looking for?