用 CLI 测试 Stripe Webhook

---
name: test-stripe-webhooks-workflow
description: "把测试事件转发到本地端点，触发已知 fixture，并验证签名处理和幂等性。"
---

# 测试 Stripe Webhook

## 适用目标

证明 Webhook handler 能处理测试事件，不触及真实客户或资金。

## 证据边界

- 工具状态分别标注 `docs-verified` 与真实独立执行；二者不能互换。
- 当前注册表没有记录某次工具执行具体由哪个 Agent 完成，因此不能把“兼容 Agent”称为“已测试 Agent”。
- 执行前重新核对目标账户、环境、版本与官方文档。
- 不自动执行 R2、R3 或任何标记为需要确认的步骤；必须在执行前获得明确批准。

## 推荐工具、安装与认证

- **Stripe CLI**（证据：`docs-verified`，文档检查：`2026-07-10`，未记录独立执行版本）
  - 安装：`brew install stripe/stripe-cli/stripe`
  - 认证：browser login, restricted API key
  - 最小权限：使用受限测试模式密钥，并在每次写操作前确认账号和 livemode。

## 输入合同

- 本地 Webhook URL
- Stripe 测试账户
- 事件类型
- 预期应用状态

## 输出合同

- 转发会话
- 测试事件 ID
- Handler 日志
- 投递与状态断言

## 安全工作流

1. **开始测试转发** — 登录目标测试账户，把事件转发到本地 handler。
   - 输入: 测试账户和本地端点
   - 输出: Webhook 签名密钥与转发会话
   - 风险: `read-only`
   - 命令: `stripe listen --forward-to localhost:3000/api/webhooks/stripe`
2. **触发 fixture** — 生成文档定义的测试事件，并保持事件类型和账户可见。
   - 输入: 选定的测试事件类型
   - 输出: 测试事件与投递尝试
   - 风险: `remote-write`
   - 命令: `stripe trigger payment_intent.succeeded`
3. **验证行为** — 检查状态码、签名、幂等性、日志和预期测试数据。
   - 输入: 投递输出和应用日志
   - 输出: 带事件 ID 的通过/失败断言
   - 风险: `read-only`

## 必须先确认

- 使用任何 live-mode 凭证或命令
- 在共享测试账户触发事件
- 创建、退款或取消真实支付对象

## 回滚

- 按需删除一次性测试 fixture
- 用项目 fixture 流程重置本地测试数据
- 不要把真实资金补偿当成测试回滚

## 官方来源

- [Stripe CLI documentation](https://docs.stripe.com/stripe-cli) — 用于核对当前命令、认证、输出和操作边界。