stripe-health

Original：🇺🇸 English
Translated

Stripe webhook health diagnostics. Invoke for: webhook delivery failures, pending_webhooks issues, redirect problems (307/308), subscription sync failures, pre-deployment webhook verification, incident investigation involving Stripe.

1installs
Sourcephrazzld/claude-config
Added on

NPX Install

npx skill4agent add phrazzld/claude-config stripe-health

Tags

Translated version includes tags in frontmatter
stripe-webhookwebhook-health-checkbackend-troubleshootingpayment-integrationdiagnostic-scripts

SKILL.md Content

View Translation Comparison →

/stripe-health - Stripe Webhook Health Check

Run a comprehensive diagnostic on Stripe webhook integration.

When to Use

  • Before deploying changes to webhook handlers
  • When subscription sync issues are reported
  • After configuring new webhook endpoints
  • As part of incident investigation

Diagnostic Steps

1. Check Webhook Endpoints

bash
# List all webhook endpoints for this project
stripe webhook_endpoints list --api-key "$STRIPE_SECRET_KEY" 2>&1 | jq '.data[] | {id, url, status, enabled_events}'
Red flags:
  • Multiple endpoints for same URL (duplicate signing secrets)
  • Status != "enabled"
  • Missing critical events (checkout.session.completed, customer.subscription.*)

2. Check for Redirects (CRITICAL)

bash
# Get the webhook URL from endpoints, then check for redirects
WEBHOOK_URL=$(stripe webhook_endpoints list --api-key "$STRIPE_SECRET_KEY" 2>&1 | jq -r '.data[0].url')
echo "Testing: $WEBHOOK_URL"
curl -s -I -X POST "$WEBHOOK_URL" 2>&1 | head -5
Red flags:
  • HTTP 307/308/301/302 = REDIRECT = Stripe won't deliver webhooks
  • Must return 4xx or 5xx, NOT 3xx

3. Check Recent Event Delivery

bash
# Check last 5 events and their pending_webhooks count
stripe events list --limit 5 --api-key "$STRIPE_SECRET_KEY" 2>&1 | jq '.data[] | {id, type, created: (.created | todate), pending_webhooks}'
Red flags:
  • pending_webhooks > 0 for old events = delivery failing
  • pending_webhooks should decrease over time

4. Check for Failed Deliveries

bash
# Look for events with high pending_webhooks (failures)
stripe events list --limit 20 --api-key "$STRIPE_SECRET_KEY" 2>&1 | jq '[.data[] | select(.pending_webhooks > 0)] | length'
Red flags:
  • More than 2-3 events with pending_webhooks > 0

5. Test Live Delivery

bash
# Resend a recent event and watch logs
RECENT_EVENT=$(stripe events list --limit 1 --type checkout.session.completed --api-key "$STRIPE_SECRET_KEY" 2>&1 | jq -r '.data[0].id')
ENDPOINT_ID=$(stripe webhook_endpoints list --api-key "$STRIPE_SECRET_KEY" 2>&1 | jq -r '.data[0].id')

echo "Resending $RECENT_EVENT to $ENDPOINT_ID..."
stripe events resend "$RECENT_EVENT" --webhook-endpoint "$ENDPOINT_ID" --api-key "$STRIPE_SECRET_KEY"

echo ""
echo "Watch Vercel logs for delivery confirmation..."
echo "Run: vercel logs your-app --json | grep webhook"

Health Report Format

STRIPE WEBHOOK HEALTH CHECK
===========================
Endpoints: [count] configured
  - [url] (status: [enabled/disabled])

Redirect Check: [PASS/FAIL]
  - [url] returns [status code]

Recent Delivery: [PASS/WARN/FAIL]
  - [X] events with pending_webhooks > 0

Recommendation: [action if any issues found]

Common Issues & Fixes

SymptomLikely CauseFix
pending_webhooks stays highRedirect or wrong URL
curl -I
the URL, update to canonical domain
Duplicate endpointsCreated endpoint twiceDelete older one, keep one with matching secret
Events not appearingWrong events enabledUpdate endpoint to include required events
Signature verification failsWrong secret in envGet secret from Stripe dashboard, update env