Stripe Webhook 訂閱同步完全指南：TG-Staff 支付回呼、套餐生效與續費取消處理

對於使用 Telegram Bot 做客服或營運的團隊，訂閱管理是 SaaS 產品的核心環節。用戶支付成功，套餐何時生效？續費失敗，功能是否立即降級？取消訂閱後，資料會不會遺失？這些問題如果依賴人工核對支付狀態，不僅效率低，還容易出錯。TG-Staff 透過整合 Stripe Webhook 訂閱同步 機制，實現了從支付成功到套餐生效的全自動化閉環。本文將從技術架構、事件回呼邏輯到邊界場景處理，帶你徹底理解這一流程。

---

為什麼 Stripe Webhook 對 TG-Staff 訂閱管理至關重要

Stripe Webhook 的本質是即時事件通知。當使用者在 Stripe Checkout 完成支付、續費成功或取消訂閱時，Stripe 會向 TG-Staff 預先配置的端點傳送 HTTP POST 請求，攜帶完整的事件資料。TG-Staff 解析並驗證後，立即更新使用者套餐狀態。

這種機制替代了兩個常見痛點：

• 手動核對：無需營運人員登入 Stripe Dashboard 查看支付記錄，再回 TG-Staff 控制台手動升級套餐。
• 延遲生效：傳統輪詢方式可能每隔幾分鐘才檢查一次支付狀態，導致使用者付款後要等待才能使用進階功能。Webhook 回呼通常在 1–3 秒內完成同步。

對團隊而言，這意味著 套餐生效、續費延期、取消降級 三個關鍵動作都可以依賴 Stripe Webhook 自動完成，減少客服諮詢量，提升使用者體驗。

---

TG-Staff 訂閱同步的整體架構

整個同步鏈路分為三個階段：支付發起、Webhook 回呼、套餐更新。理解這三步的互動關係，有助於你排查同步問題或訂製支付流程。

支付發起階段：Stripe Checkout 與會話建立

使用者在 TG-Staff 控制台「我的訂閱」頁面選擇套餐週期（30/90/180/360 天）後，點擊「Stripe 支付」按鈕。TG-Staff 後端呼叫 Stripe API 建立 Checkout Session，包含以下關鍵參數：

• success_url：支付成功後跳轉回 TG-Staff 控制台
• cancel_url：支付取消後跳轉回套餐選擇頁
• metadata：攜帶使用者 ID、套餐類型、週期等自訂欄位，用於回呼時識別使用者

使用者完成 Stripe 支付表單（信用卡、Google Pay、Apple Pay 等）後，Stripe 將使用者重新導向至 success_url。此時前端顯示「支付成功，正在同步套餐…」，而後端同步尚未完成——真正的套餐更新依賴 Webhook 回呼。

回呼階段：Webhook 事件類型與 TG-Staff 的監聽邏輯

Stripe 向 TG-Staff 預配置的 Webhook 端點傳送事件。TG-Staff 監聽的核心事件包括：

事件類型	觸發場景	同步動作
checkout.session.completed	使用者首次支付或續費成功	驗證簽名，提取 subscription ID、週期、使用者 ID，更新套餐狀態
invoice.payment_succeeded	自動續費成功（如月付到期扣款）	延長套餐到期時間，保持功能不變
customer.subscription.updated	套餐變更（升級、降級、週期調整）	更新套餐級別與週期
customer.subscription.deleted	使用者取消訂閱或 Stripe 自動取消（如支付失敗超期）	標記套餐到期時間，當前週期內功能保留

TG-Staff 收到事件後，首先驗證 Stripe 簽名（使用 Webhook Secret），防止偽造回呼。驗證通過後，解析事件資料中的 metadata 欄位，比對 TG-Staff 內部使用者 ID，然後更新資料庫中的套餐記錄。

同步完成：套餐狀態在控制台「我的訂閱」頁面的即時更新

更新成功後，TG-Staff 控制台「我的訂閱」頁面會即時反映新套餐資訊：套餐名稱、到期時間、座席額度、可用功能（如分流連結、內容風控等）。使用者無需重新整理頁面即可看到變化（透過 WebSocket 或輪詢機制）。

---

支付成功回呼：套餐即時生效的處理邏輯

checkout.session.completed 是最關鍵的事件。TG-Staff 處理此事件的詳細流程如下。

事件驗證與資料擷取

1. 簽名驗證：TG-Staff 使用 Stripe Webhook Secret 校驗請求標頭 stripe-signature。若簽名不匹配，回傳 400 狀態碼並記錄錯誤日誌。
2. 資料擷取：從事件 data.object 中取得：
   • subscription：Stripe 訂閱 ID
   • metadata.user_id：TG-Staff 內部使用者識別碼
   • metadata.plan：套餐類型（standard / pro）
   • metadata.period：週期天數（30 / 90 / 180 / 360）
3. 冪等性檢查：同一事件可能因網路重試被多次投遞。TG-Staff 使用事件 ID 做去重，確保套餐狀態只更新一次。

套餐權限映射與啟用

擷取資料後，TG-Staff 根據套餐類型和週期更新使用者權限表：

• 坐席額度：標準版 3 個，專業版 5 個，更高週期可能包含額外坐席（以官網套餐頁為準）。
• 功能開關：標準版啟用分流連結、會話分流、AI 翻譯（有配額）；專業版額外啟用內容風控、無限翻譯、使用者畫像、TG 主題聊天背景。
• 到期時間：目前時間 + 週期天數。例如使用者購買 90 天專業版，到期時間為目前時間 + 90 天。

同時，TG-Staff 會將 Stripe Subscription ID 關聯到使用者記錄，用於後續續費、取消事件的匹配。

回呼失敗的重試機制與日誌排查

若 TG-Staff 在處理回呼時遇到臨時錯誤（如資料庫超時、網路抖動），會回傳 5xx 狀態碼。Stripe 內建重試機制：第一次失敗後等待 5 分鐘重試，第二次 10 分鐘，第三次 30 分鐘，最多重試 3 次。

如果 3 次重試均失敗，Stripe 會在 Dashboard 的 Webhook 日誌中標記為「失敗」。此時，使用者可在 TG-Staff 控制台「我的訂閱」頁面手動點擊「同步狀態」按鈕，觸發一次強制檢查。若仍無法解決，聯繫 @tgstaff_robot 技術支援。

---

續費與取消：Stripe Webhook 同步的邊界場景

除了首次支付，日常營運中更常見的是續費成功和取消訂閱。TG-Staff 透過不同事件區分處理。

續費成功：週期延長與功能保持不變

當 Stripe 自動扣款續費成功時，觸發 invoice.payment_succeeded 事件。TG-Staff 邏輯如下：

• 取得 subscription 關聯的 TG-Staff 使用者
• 檢查目前套餐到期時間，向後延長一個週期（例如月付延長 30 天）
• 功能權限不變：坐席額度、分流連結、翻譯配額等均保持原配置

此過程完全自動化，使用者無需任何操作。如果續費失敗（如信用卡過期），Stripe 會發送 invoice.payment_failed 事件，TG-Staff 目前不會立即降級，而是等待 Stripe 的自動重試（通常 3–5 次，間隔幾天）。若最終失敗，Stripe 會發送 customer.subscription.deleted 事件。

取消訂閱：套餐到期前的降級提醒與資料保留策略

使用者透過 Stripe Billing Portal 或聯繫客服取消訂閱後，Stripe 發送 customer.subscription.deleted 事件。TG-Staff 的處理策略是：

• 標記到期時間：取消後，套餐到期時間不變（即目前付費週期結束日期）。
• 功能保留：在週期結束前，使用者可繼續使用所有已購功能，包括坐席、分流連結、內容風控等。
• 降級觸發：週期結束後，套餐自動降級為免費版（無坐席額度、無分流連結、翻譯配額歸零）。但使用者資料（會話記錄、使用者畫像、Bot 配置）不會刪除，僅限制超出免費額度的功能。

例如，用戶購買了 90 天專業版，在第 30 天取消訂閱。剩餘 60 天內功能依然完整可用。第 90 天到期後，坐席從 5 個降至 0 個，分流鏈接功能關閉，但歷史對話記錄仍可在控制台查看。

---

USDT 鏈上支付與 Stripe 雙通道的同步差異

TG-Staff 同時支持 USDT（TRC20）鏈上支付和 Stripe 支付，但兩者的同步機制有顯著差異。

對比維度	Stripe 支付	USDT 鏈上支付
回調觸發	Stripe Webhook 即時推送	無自動事件推送
確認時間	支付完成即回調（1–3 秒）	依賴區塊鏈確認數（通常 1–3 分鐘）
同步方式	自動，無需人工干預	需用戶手動在控制台提交交易哈希，或等待 TG-Staff 後台掃描
失敗處理	Stripe 自動重試 3 次	需要聯繫客服手動核對鏈上記錄

Stripe Webhook 的自動化優勢明顯：支付成功 → 套餐即時生效，無需用戶額外操作。而 USDT 支付需要用戶手動提交交易哈希，TG-Staff 後台掃描確認後更新套餐，即時性較低。對於需要快速開通高級功能的團隊，推薦優先使用 Stripe 支付。

---

調試與排錯：Webhook 同步失敗的常見原因

即使 Stripe Webhook 機制成熟，仍可能因配置或網絡問題導致同步失敗。以下是典型問題及排查路徑。

1. Webhook 簽名校驗失敗：Stripe Dashboard 中 Webhook 端點配置的 Secret 與 TG-Staff 要求的不一致。解決：在 Stripe Dashboard → Developers → Webhooks → 點擊端點 → 複製 Signing secret，粘貼到 TG-Staff 控制台對應配置項。

2. 網絡防火牆攔截：TG-Staff 服務器 IP 被防火牆或 CDN 規則攔截，導致 Stripe 無法連接。解決：檢查服務器安全組是否放行 Stripe 的 IP 範圍（詳見 Stripe 官方文檔）。

3. 事件類型未啟用：Stripe Webhook 端點默認只監聽部分事件。若 checkout.session.completed 未勾選，則無法接收支付成功回調。解決：在 Stripe Dashboard 的 Webhook 端點設置中，添加所需事件類型。

4. 重複事件導致冪等性異常：Stripe 可能因網絡重試投遞同一事件多次。TG-Staff 的事件 ID 去重機制通常能處理，但如果去重緩存過期，可能導致套餐狀態被錯誤覆蓋。解決：檢查 TG-Staff 日誌中的 event_id 重複記錄，聯繫技術支持清除緩存。

---

常見問題

問： Stripe Webhook 回調後，方案不會立即生效怎麼辦？

答： 檢查 Stripe Dashboard 中 Webhook 端點是否配置正確，並確保 checkout.session.completed 事件已啟用。TG-Staff 收到回調後通常 1–3 秒內同步方案狀態。若超過 30 秒未生效，請檢查 TG-Staff 控制台「我的訂閱」頁面是否有錯誤提示，或聯繫 @tgstaff_robot 技術支援。

問： 用戶透過 USDT 支付後，Stripe Webhook 會觸發嗎？

答： 不會。USDT 鏈上支付不經過 Stripe，因此不觸發 Stripe Webhook。TG-Staff 透過獨立的鏈上交易確認邏輯處理 USDT 支付，確認時間取決於區塊鏈網路確認數（通常 1–3 分鐘），與 Stripe 回調的即時性不同。

問： 訂閱取消後，Webhook 會立即同步嗎？資料會遺失嗎？

答： 是。customer.subscription.deleted 事件會立即回調 TG-Staff，但方案功能僅在當前付費週期結束後降級。週期內資料（如對話記錄、用戶畫像）不會遺失；降級後僅限制超出方案額度的功能，如坐席數超標時新對話無法分配。建議在到期前透過 Billing Portal 恢復訂閱。

問： 如果 Stripe Webhook 回調失敗，TG-Staff 有重試機制嗎？

答： 有。Stripe 內建自動重試機制（最多 3 次，間隔遞增）。TG-Staff 端也會記錄回調日誌，若連續失敗，用戶可在控制台「我的訂閱」頁面手動觸發同步，或聯繫 @tgstaff_robot 手動修復。常見失敗原因包括網路防火牆攔截、Webhook 簽章過期（需定期重新整理 Secret）。

問： 是否支援多 Stripe 帳戶（如多項目多商戶）的 Webhook 同步？

答： 當前 TG-Staff 支援單個 Stripe 帳戶的 Webhook 配置，適用於統一管理多個 Telegram Bot 專案。若需多商戶分離支付，建議透過 Stripe Connect 或分帳戶方案，並聯繫 TG-Staff 團隊確認客製化支援。

---

準備好體驗 Stripe Webhook 自動同步的訂閱管理了嗎？

註冊 TG-Staff 免費試用 3 天，無需自建 Webhook 伺服器，即可體驗支付回調、方案即時生效、續費與取消自動處理的完整流程。

• 註冊試用：https://app.tg-staff.com/
• 查閱 Webhook 配置文件：https://docs.tg-staff.com/
• 聯繫技術支援：@tgstaff_robot