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 或一般的結帳會話管理不在本技能範圍內。