integrating-stripe-webhooks

此技能旨在协助处理 Stripe webhook 集成困难的开发者，特别是需要处理原始请求主体 (raw request body) 的场景。由于许多现代 Web 框架（如 Fastify、Express 与 FastAPI）默认会自动解析 JSON 主体，这通常会导致 Stripe 的签名验证失败，进而触发“Raw body not available”或 400 签名验证错误。此技能提供精确的框架专属代码模式，确保在中间件干预前访问原始缓冲区，从而确保与 Stripe API 的安全通信。

除了主体解析外，本技能也解决了常见的 TypeScript 类型不匹配问题。开发者在尝试直接访问订阅对象上的 'current_period_start' 等属性时常会遇到错误，因为这些字段其实位于订阅项目数据结构的深处。通过遵循此文档中的模式，开发者可以有效避免这些运行时错误并成功处理复杂的 Stripe 事件。

• 提供在 Fastify、Express 与 FastAPI 中配置原始主体解析器的样板模式，确保 constructEvent() 验证成功。

• 提供针对路由注册不当导致 API 前缀失效而引发 404 错误的详细调试策略。

• 提供访问订阅期间日期的稳健方法，包含当根订阅对象缺少特定字段时的后备逻辑。

• 包含针对结账 URL 中的动态参数进行 URL 编码的技巧，以防止 URI 格式验证失败。

• 请务必在任何 JSON 解析中间件之前配置原始主体解析器。

• 若遇到关于订阅期间的 TypeError，请检查 subscription.items.data[0] 而非根目录。

• 确保 STRIPE_WEBHOOK_SECRET 环境变量已正确加载并用于每次请求验证。

• 使用提供的实现检查清单以确保全面处理 webhook 事件，包含及时返回 200 响应以防止事件重试。

• 请注意，此技能仅限于后端 webhook 处理；前端 Stripe Elements 或一般的结账会话管理不在本技能范围内。