Back to Details

stripe-health

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

/stripe-health - Stripe Webhook Health Check

/stripe-health - Stripe Webhook健康检查

Run a comprehensive diagnostic on Stripe webhook integration.
对Stripe Webhook集成进行全面诊断。

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
  • 部署Webhook处理器变更之前
  • 收到订阅同步问题反馈时
  • 配置新的Webhook端点之后
  • 作为事件调查的一部分

Diagnostic Steps

诊断步骤

1. Check Webhook Endpoints

1. 检查Webhook端点

bash
undefined
bash
undefined

List all webhook endpoints for this project

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.*)
stripe webhook_endpoints list --api-key "$STRIPE_SECRET_KEY" 2>&1 | jq '.data[] | {id, url, status, enabled_events}'

**红色预警:**
- 同一URL对应多个端点（重复签名密钥）
- 状态不等于"enabled"
- 缺少关键事件（checkout.session.completed、customer.subscription.*）

2. Check for Redirects (CRITICAL)

2. 检查重定向（关键）

bash
undefined
bash
undefined

Get the webhook URL from endpoints, then check for redirects

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

**红色预警:**
- HTTP 307/308/301/302 = 重定向 = Stripe不会投递Webhook
- 必须返回4xx或5xx，不能是3xx

3. Check Recent Event Delivery

3. 检查近期事件投递

bash
undefined
bash
undefined

Check last 5 events and their pending_webhooks count

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
stripe events list --limit 5 --api-key "$STRIPE_SECRET_KEY" 2>&1 | jq '.data[] | {id, type, created: (.created | todate), pending_webhooks}'

**红色预警:**
- 旧事件的pending_webhooks > 0 = 投递失败
- pending_webhooks应随时间减少

4. Check for Failed Deliveries

4. 检查失败的投递

bash
undefined
bash
undefined

Look for events with high pending_webhooks (failures)

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
stripe events list --limit 20 --api-key "$STRIPE_SECRET_KEY" 2>&1 | jq '[.data[] | select(.pending_webhooks > 0)] | length'

**红色预警:**
- 超过2-3个事件的pending_webhooks > 0

5. Test Live Delivery

5. 测试实时投递

bash
undefined
bash
undefined

Resend a recent event and watch logs

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"
undefined
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"
undefined

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]
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
症状可能原因修复方法
pending_webhooks数值持续偏高重定向或URL错误使用
curl -I
检查URL，更新为标准域名
重复端点重复创建了端点删除旧的端点，保留与密钥匹配的那个
事件未出现未启用正确的事件更新端点以包含所需事件
签名验证失败环境变量中的密钥错误从Stripe控制台获取密钥，更新环境变量