Skip to main content
如果你的 Webhook 端點未返回 2xx 狀態碼,啟潤支付將自動重試投遞。

重試計畫

對於本文檔中的訂單和爭議事件,啟潤支付最多進行 7 次投遞:首次投遞加 6 次重試。 等待時間從前一次投遞失敗時計算,實際投遞可能稍晚。累計 7 次投遞失敗後,Webhook 被標記為失敗並停止自動重試。

什麼算作失敗

以下情況 Webhook 投遞被視為失敗:
  • 你的端點返回非 2xx HTTP 狀態碼(如 400、500)
  • 你的端點在 10 秒內未完成回應
  • 無法連接到你的伺服器(DNS 錯誤、連線被拒絕、逾時)
2xx 回應(如 200、201、204)即被視為投遞成功,不論回應本體內容如何。

處理重試

由於 Webhook 可能被重試,你的端點應該是冪等的 — 多次處理同一事件應產生相同的結果。

使用事件 ID 去重

每個 Webhook 事件都有唯一的 id 欄位。透過唯一約束持久化已處理的事件 ID,並在同一交易中提交業務變更和處理標記:
上述資料庫方法用於說明交易要求,請按你的儲存系統實作。業務操作也應以穩定識別碼保護,例如付款履約使用 order_id,退款使用 refund_id。爭議更新不能僅按案件 ID 去重,因為一個案件可能產生多次更新。

快速返回 200

處理時間較長時,應先驗證簽名,將事件持久化到接收表或佇列,再返回 200。工作程序隨後處理並負責自己的重試。若持久化失敗,請返回非 2xx 回應,讓 Kyren 重試:

監控 Webhook 投遞

排查投遞問題時,請將 Kyren Webhook 事件與你自己的服務端日誌對照。請記錄:
  • 你設定的 Webhook URL
  • 事件類型和訂單號
  • 你的服務端收到請求的時間
  • 你的服務端返回的回應碼或錯誤
如果需要 Kyren 協助檢查投遞嘗試,請帶上這些資訊聯絡支援。

故障排除