OpenParable
Skip to content
← Back to skills

Stripe Local Dev

Apps & Automation
stripe-local-dev

Stripe Local Dev is an Agent Skill for apps & automation published in the majiayu000/claude-skill-registry repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/majiayu000/claude-skill-registry/blob/HEAD/skills/data/stripe-local-dev/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/stripe-local-dev, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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

  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:

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

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