Telegram Bot Stripe Webhook 訂閱同步指南：SaaS 套餐狀態常見故障與修復

當你的 Telegram Bot 客服平台（如 TG-Staff）整合 Stripe 支付後，最怕遇到的情況莫過於：用戶明明付了費，系統卻顯示「試用已過期」；或者用戶取消了訂閱，控制台卻仍顯示「專業版」。這些問題的根源，往往在於 Telegram Bot Stripe Webhook 的訂閱狀態同步機制出了岔子。

本文將圍繞 TG-Staff 等 Telegram Bot SaaS 平台，拆解 Stripe Webhook 同步套餐狀態的 5 大常見故障點，並提供可落地的排查步驟與檢查清單。無論你是剛接入支付、還是正在排查用戶反饋的付費異常，這篇文章都能幫你快速定位問題。

---

為什麼 Telegram Bot SaaS 需要 Stripe Webhook 同步訂閱狀態？

Telegram Bot 的客服 SaaS 平台（如 TG-Staff）通常採用 套餐制：免費試用 → 標準版 → 專業版。用戶通過 Stripe 完成支付後，平台需要即時獲取用戶的付費狀態，才能正確開放以下功能：

• 坐席額度：控制同時接待的客服人數
• 分流鏈接：廣告引流歸因
• 內容風控：內控管理與錢包地址監控
• 批量群發與自動翻譯：運營效率工具

Stripe Webhook 就是連接「支付成功」與「功能開放」的橋樑。當用戶在 Stripe 完成支付、續費、取消或退款時，Stripe 會向平台服務端發送 HTTP 回調（Webhook）。平台收到後更新用戶套餐狀態。

如果 Webhook 失效或延遲，就會出現：

• 付費用戶仍被限制在免費版
• 過期用戶仍享有專業版功能（導致計費漏洞）
• 坐席登入後看到「套餐已過期」的報錯

因此，確保 Telegram Bot Stripe Webhook 的配置正確、事件完整、簽名驗證通過，是 SaaS 運營的基石。

---

故障點 1：Stripe Webhook 端點未正確配置或簽名驗證失敗

這是最常見、也最容易修復的問題。Stripe 在發送 Webhook 時會攜帶簽名（stripe-signature），平台需要驗證簽名來確認請求確實來自 Stripe，而非惡意偽造。

常見配置錯誤

錯誤類型	表現
Webhook 端點 URL 填寫錯誤	Stripe Dashboard 顯示「Endpoint 不可達」
Signing Secret 未更新或填錯	簽名驗證失敗，平台拒絕處理 Webhook
HTTPS 證書過期或無效	Stripe 無法發送請求到你的端點
防火牆/反向代理攔截	請求被伺服器丟棄

如何確認 Webhook 簽名是否通過？

1. 登入 Stripe Dashboard → 左側選單「Developers」→「Webhooks」
2. 找到你配置的端點，點擊進入詳情頁
3. 查看 Webhook Attempts（嘗試記錄）列表
4. 篩選狀態為「Failed」的請求，點擊查看詳情
   • 如果錯誤是 Signature verification failed → 檢查 Signing Secret
   • 如果錯誤是 HTTP 4xx/5xx → 檢查端點 URL 和伺服器日誌

重新生成 Signing Secret 後的更新步驟

如果你不小心洩露了密鑰，或需要輪換密鑰，請按以下步驟操作：

1. 在 Stripe Webhook 端點詳情頁，點擊「Reveal live secret key」
2. 點擊「Rotate signing secret」生成新密鑰（以 whsec_ 開頭）
3. 複製新密鑰
4. 登入 TG-Staff 控制台 → 設定 → 支付配置 → 更新 Stripe Webhook 簽名密鑰
5. 儲存後，在 Stripe 端發送一條測試事件（如 checkout.session.completed），確認返回 200 OK

---

故障點 2：Webhook 事件類型訂閱遺漏導致關鍵狀態未觸發

Stripe 支援數十種事件類型。TG-Staff 等平台依賴以下核心事件來同步套餐狀態：

事件類型	觸發時機	對應操作
checkout.session.completed	使用者完成 Checkout 付款	啟用/升級套餐
customer.subscription.updated	訂閱續費、降級、週期變更	更新套餐到期時間
customer.subscription.deleted	取消訂閱（目前週期結束後生效）	標記套餐過期
invoice.payment_succeeded	續費帳單付款成功	延長有效期限
invoice.payment_failed	續費失敗	觸發降級提醒

常見遺漏：很多使用者只訂閱了 checkout.session.completed，忘記了 customer.subscription.updated。這會導致：

• 使用者續費成功 → Webhook 未觸發 → 套餐狀態未更新
• 使用者手動降級 → 平台不知情 → 仍顯示原套餐

如何驗證事件是否被正確接收？

1. 在 Stripe Webhook 詳情頁，點擊「Send test webhook」
2. 選擇 customer.subscription.updated 事件類型
3. 發送後查看平台日誌（或聯絡 TG-Staff 客服確認）
4. 如果平台返回 200 OK，表示事件訂閱正確

---

故障點 3：方案週期與 Stripe 訂閱週期不匹配導致的過期誤判

TG-Staff 支援 30/90/180/360 天 的多週期方案，這意味著用戶可以選擇購買 90 天標準版，而非固定月度訂閱。如果 Stripe 端的產品週期設定與控制台方案定義不一致，會導致 Webhook 返回的 current_period_end 時間戳計算錯誤。

典型錯誤場景

• Stripe 產品設為月度（30 天），但用戶購買了 90 天方案：系統可能只計算了 30 天，然後提前標記過期
• 年付折扣透過優惠券實現，而非 360 天產品：Stripe 返回的 current_period_end 是 30 天，導致平台誤判

如何比對週期？

1. 在 Stripe 端檢查產品設定：

   • 進入 Stripe Dashboard → Products → 找到你的方案產品
   • 查看「Pricing」中的 Billing period 是否與控制台定義的週期一致
   • 例如：90 天方案 → Stripe 端應設為 Every 90 days

2. 在 TG-Staff 控制台檢查：

   • 登入 https://app.tg-staff.com/ → 「我的訂閱」
   • 查看當前方案的「到期時間」是否與你支付的週期一致
   • 如果相差超過 1 天，表示週期不匹配

最佳實踐：在 Stripe 端為每個週期建立獨立的產品（如「Standard 90 Days」「Pro 360 Days」），而非用一個產品疊加折扣。

---

故障點 4：Webhook 重試機制與冪等性處理失敗

Stripe 在 Webhook 發送失敗時會自動重試——最多持續 3 天，重試間隔逐漸拉長（從幾秒到幾小時）。如果平台服務端未正確處理 冪等性（Idempotency），可能導致：

• 同一個事件被處理多次 → 方案狀態被重複覆蓋
• 重試請求與原始請求順序混亂 → 狀態回滾到舊版本

冪等性是什麼？

簡單說，就是平台需要確保同一個 Webhook 事件只被處理一次，即使 Stripe 發送了多次。Stripe 會在每個請求頭中攜帶 Idempotency-Key，平台應記錄已處理過的 Key，重複請求直接返回 200 OK 但不執行邏輯。

如何排查冪等性問題？

1. 查看 TG-Staff 後台日誌（或聯絡客服）是否出現以下模式：

   • 同一個 event_id 被處理了多次
   • 方案狀態在短時間內反覆變化（啟用→過期→啟用）

2. 如果懷疑是冪等性處理失敗，聯絡 @tgstaff_robot 客服，提供你的 Stripe 帳戶 ID 和 Webhook 發送時間，客服可以拉取服務端日誌分析。

---

故障點 5：USDT 鏈上支付與 Stripe 雙通道下的狀態同步衝突

TG-Staff 支援 Stripe 信用卡支付 和 USDT（TRC20）鏈上支付 兩種方式。兩種通道的訂閱狀態管理邏輯不同：

支付方式	狀態同步機制	延遲
Stripe	即時 Webhook 回呼	秒級
USDT	鏈上對帳（人工或自動化）	1–5 分鐘（區塊確認後）

衝突場景：

• 用戶先透過 Stripe 試用 3 天，然後改用 USDT 續費 90 天
• USDT 到帳後，系統因未正確處理「從 Stripe 切換到 USDT」的狀態，導致方案仍顯示為試用期
• 或者，Stripe 訂閱已取消，但 USDT 支付後的新訂閱未正確覆蓋舊狀態

雙支付通道下的訂閱狀態檢查清單

1. 登入控制台 → 「我的訂閱」
2. 查看「支付方式」欄位：顯示 Stripe 還是 USDT？
3. 查看「到期時間」：是否與你的支付週期一致？
4. 如果有異常，點擊「重新整理狀態」按鈕（如有）或聯絡客服

從 Stripe 切換到 USDT 支付時的注意事項

• 不要同時啟用兩個訂閱：如果 Stripe 訂閱仍在有效期內，USDT 支付會建立第二個訂閱。系統需要合併處理，否則可能出現雙套餐狀態。
• 建議先取消 Stripe 訂閱：在 Stripe 端取消當前訂閱（當前週期仍有效），然後用 USDT 購買新套餐。這樣新舊訂閱不會衝突。
• 檢查到期時間疊加：如果 Stripe 訂閱還有 20 天到期，USDT 購買 90 天後，總有效期應為 110 天。如果系統只顯示 90 天，表示疊加邏輯未生效。

---

故障排查檢查清單（Checklist）

以下是一份可複製的檢查清單，建議逐項勾選：

#	檢查項	狀態（✔/✘）
1	Stripe Webhook 端點 URL 正確，且 HTTPS 證書有效	☐
2	Signing Secret 已正確填寫到 TG-Staff 控制台，且與 Stripe 端一致	☐
3	Webhook 事件已勾選 checkout.session.completed、customer.subscription.updated、customer.subscription.deleted	☐
4	Stripe 產品週期（如 30/90/180/360 天）與 TG-Staff 套餐定義一致	☐
5	Webhook 日誌中無重複處理的 event_id（冪等性正常）	☐
6	如果使用 USDT 支付，控制台「我的訂閱」顯示正確的支付方式和到期時間	☐
7	免費試用到期後續費，等待 5 分鐘後重新整理控制台確認狀態已更新	☐

---

常見問題

問：TG-Staff 的免費試用到期後，為什麼我續費了但坐席還是不可用？

答：試用到期後系統可能已將套餐標記為過期。續費成功後，Stripe Webhook 會傳送 customer.subscription.updated 事件，TG-Staff 收到後恢復套餐狀態。若等待 5 分鐘後仍不可用，請檢查 Stripe Webhook 日誌中是否有該事件的傳送記錄，或聯絡 @tgstaff_robot 客服手動同步。

問：我在 Stripe 上取消了訂閱，但 TG-Staff 控制台仍顯示標準版，為什麼？

答：取消訂閱（customer.subscription.deleted 事件）可能因 Webhook 配置缺失而未觸發。請確認 Stripe Webhook 設定中已勾選 customer.subscription.deleted 事件。此外，取消後當前週期仍有效，直到週期結束才會降級。

問：Webhook 簽名驗證失敗如何修復？

答：在 Stripe Dashboard 的 Webhook 設定頁面，複製「Signing Secret」（以 whsec_ 開頭），貼上到 TG-Staff 控制台對應的 Webhook 配置欄位中。注意：重新產生金鑰後需要同步更新，否則簽名驗證會持續失敗。

問：USDT 支付後，套餐狀態多久能同步？

答：USDT 支付為鏈上對帳模式，非即時 Webhook 觸發。通常到帳確認後（1–3 個區塊確認，約 1–5 分鐘），TG-Staff 後台會完成對帳並更新套餐。若超過 30 分鐘仍未更新，建議聯絡 @tgstaff_robot 並提供交易雜湊（TxID）人工處理。

問：我使用了年付折扣，但 Webhook 返回的週期是月度，套餐會提前過期嗎？

答：不會。TG-Staff 的年付折扣透過 Stripe 的「多週期套餐」實現，Stripe 端建立的是 360 天的訂閱產品，current_period_end 時間戳正確對應年付到期日。如果發現時間不符，請檢查 Stripe 產品設定中週期是否為 360 天，而非月度產品疊加折扣。

---

下一步：確保你的 Telegram Bot SaaS 支付鏈路暢通

Telegram Bot Stripe Webhook 的配置直接影響用戶付費體驗。如果你正在使用或考慮使用 TG-Staff 管理 Telegram Bot 客服，建議按以下步驟操作：

1. 註冊免費試用：前往 https://app.tg-staff.com/ 建立帳戶
2. 綁定 Stripe 支付：在控制台完成 Stripe 帳號綁定與 Webhook 配置
3. 執行檢查清單：對照上文清單逐項確認配置正確
4. 遇到問題？ 隨時聯絡 @tgstaff_robot 客服，提供你的帳戶資訊與故障現象

更多技術細節請查閱官方文件：https://docs.tg-staff.com/