Agent-Skills.md

Agent Skills: /stripe-local-dev

|

UncategorizedID: phrazzld/claude-config/stripe-local-dev

Repository

phrazzld/claude-config
phrazzld
31

Install this agent skill to your local

pnpm dlx add-skill https://github.com/phrazzld/claude-config/tree/HEAD/skills/stripe-local-dev

Skill Files

Browse the full folder contents for stripe-local-dev.

Download Skill

Loading file tree…

skills/stripe-local-dev/SKILL.md

Skill Metadata

Name
stripe-local-dev
Description
|

/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

Also: if checkout succeeds but access stays locked and you see:

  • stripe_webhook_missing_convex_token
  • Webhook token is not configured then CONVEX_WEBHOOK_TOKEN is missing/mismatched between Next runtime and Convex.

Architecture Decision

| Webhook Location | Secret Sync Target | Restart? | Recommendation | |-----------------|-------------------|----------|----------------| | Convex HTTP (convex/http.ts) | bunx convex env set (or npx) | 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:

bun run dev  # or: 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 dev server or re-sync secret | | "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) | | Checkout succeeds, still locked, confirm/webhook 5xx | Missing/mismatched CONVEX_WEBHOOK_TOKEN | Ensure token parity, restart Next.js |

Related Skills

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