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

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

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

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)

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

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

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

常见问题与修复方案

Symptom	Likely Cause	Fix
pending_webhooks stays high	Redirect or wrong URL	`curl -I` the URL, update to canonical domain
Duplicate endpoints	Created endpoint twice	Delete older one, keep one with matching secret
Events not appearing	Wrong events enabled	Update endpoint to include required events
Signature verification fails	Wrong secret in env	Get secret from Stripe dashboard, update env

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