跳轉到主要內容
Webhook 允許啟潤支付在你的帳戶中發生事件時（如支付成功或結款完成）向你的伺服器發送即時通知。

​
工作原理

  1. 事件發生（如客戶完成付款）
  2. 啟潤支付向你配置的 Webhook URL 發送 HTTP POST 請求
  3. 請求中包含用於驗證的簽名
  4. 你的伺服器處理事件並返回 200 回應

​
配置 Webhook

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

​
Webhook 載荷

每個 Webhook 請求包含以下請求標頭：
請求標頭描述
Content-Typeapplication/json
X-Kyren-SignatureHMAC-SHA256 簽名，用於驗證
X-Kyren-Timestamp發送 Webhook 時的 Unix 毫秒時間戳
請求本體是一個 JSON 物件： 
{
  "id": "evt_abc123",
  "type": "order.paid",
  "created_at": 1736932500000,
  "data": {
    "order_id": "order_def456",
    "product_id": "prod_abc123",
    "customer_email": "customer@example.com",
    "amount": "9.99",
    "currency": "USD",
    "net_amount": "9.29",
    "paid_at": 1736932500000,
    "metadata": {}
  }
}

​
最佳實踐

驗證簽名

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

快速返回 200

收到 Webhook 後立即返回 200 回應。如果處理需要較長時間，請非同步處理。

處理重複事件

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

使用訊息佇列

在生產環境中，考慮將 Webhook 事件推送到訊息佇列（如 RabbitMQ、SQS）以實現可靠處理。

​
下一步

事件類型

查看所有事件類型

簽名驗證

驗證 Webhook 簽名

重試機制

了解重試行為