Skip to main content
Webhook 允許啟潤支付在付款或退款成功時向你的伺服器發送通知。支援的事件及可選爭議通知見事件類型。

工作原理

  1. 事件發生(如客戶完成付款)
  2. 啟潤支付向你配置的 Webhook URL 發送 HTTP POST 請求
  3. 請求中包含用於驗證的簽名
  4. 你的伺服器驗證簽名、持久化事件,並在 10 秒內返回 200
  5. 工作程序冪等處理已持久化的事件,並負責自己的重試

配置 Webhook

在商戶控制台中設定你的 Webhook 端點:
  1. 前往 控制台 > 開發者 > Webhook 設定
  2. 輸入你的 Webhook URL(如 https://yoursite.com/webhooks/kyren)
  3. 複製你的 Webhook 密鑰 — 用於驗證簽名
你的 Webhook URL 必須:
  • 使用 HTTPS(生產環境必須)
  • 可公開存取
  • 持久化成功後,在 10 秒內完成 2xx 回應

Webhook 載荷

每個 Webhook 請求包含以下請求標頭: 請求本體是一個 JSON 物件:

最佳實踐

驗證簽名

始終驗證 X-Kyren-Signature 請求標頭以確保 Webhook 的真實性。參見 Webhook 簽名驗證。

快速返回 200

驗證簽名並持久化事件後再返回 200。持久化失敗時返回非 2xx,讓 Kyren 重試。

處理重複事件

使用事件 id 進行去重。由於重試機制,你的端點可能會收到同一事件多次。

使用訊息佇列

非同步處理時,將事件儲存到持久化接收表或佇列,儲存成功後才確認。Kyren 收到 2xx 後,工作程序需要負責自己的重試。

下一步

事件類型

查看所有事件類型

簽名驗證

驗證 Webhook 簽名

重試機制

了解重試行為