POST /v1/webhook_endpoints
GET /v1/webhook_endpoints
GET /v1/webhook_endpoints/{endpoint_id}
POST /v1/webhook_endpoints/{endpoint_id}
DELETE /v1/webhook_endpoints/{endpoint_id}
POST /v1/webhook_endpoints/{endpoint_id}/rotate_secret事件格式與驗簽見 Webhook。這裏只講端點管理。
端點屬於調用它的密鑰所在的應用，只接收該應用訂單產生的事件；一個密鑰也只能看到和修改自己應用的端點。每個應用每個環境最多配置 5 個端點，各自有獨立的簽名密鑰和事件訂閲。端點按環境隔離——沙箱端點永遠收不到正式事件。
接收所有應用事件的賬戶級端點（app_id 為 null）只能在商戶後台「開發者 → Webhook」創建和管理，API 看不到它們。
創建
curl -X POST "https://api.kukopay.com/v1/webhook_endpoints" \
-H "X-Api-Key: kuko_live_你的密鑰" \
-H "Content-Type: application/json" \
-d '{
"url": "https://api.yourshop.com/hooks/kukopay",
"description": "訂單履約服務",
"enabled_events": ["payment.succeeded", "refund.succeeded"]
}'| 參數 | 必填 | 説明 |
|---|---|---|
url | 是 | 正式環境必須是可公網訪問的 HTTPS 地址 |
description | 否 | 備註，便於在控制台區分多個端點 |
enabled_events | 否 | 訂閲的事件類型，省略為全部 |
enabled_events 傳 ["*"] 表示訂閲全部，並且會自動包含之後新增的事件類型。
簽名密鑰
{
"object": "webhook_endpoint",
"endpoint_id": "whe_8c2f41ab9d0e7635",
"app_id": "app_5f2c9e41b7a0d3c86e1f4a20",
"url": "https://api.yourshop.com/hooks/kukopay",
"enabled_events": ["payment.succeeded", "refund.succeeded"],
"status": "enabled",
"secret": "whsec_4f81a2c9...",
"secret_notice": "請立即保存該簽名密鑰，它不會再次以明文返回。"
}secret 只在創建和輪換時返回這一次。它加密存儲，之後無法再讀回明文——這正是設計目的：控制台被人看到也拿不到密鑰。沒保存就只能輪換一把新的。
更新與停用
curl -X POST "https://api.kukopay.com/v1/webhook_endpoints/whe_8c2f41ab9d0e7635" \
-H "X-Api-Key: kuko_live_你的密鑰" \
-H "Content-Type: application/json" \
-d '{ "status": "disabled" }'想暫停接收時建議改成 disabled 而不是刪除：投遞歷史掛在端點上，刪掉之後就查不到這段時間漏了什麼。
輪換簽名密鑰
curl -X POST "https://api.kukopay.com/v1/webhook_endpoints/whe_8c2f41ab9d0e7635/rotate_secret" \
-H "X-Api-Key: kuko_live_你的密鑰"簽發新密鑰，舊密鑰在 24 小時內繼續並行簽名。兩個簽名出現在同一個 X-KukoPay-Signature 頭裏（多個 v1=），任意一個驗簽通過即為合法請求。
X-KukoPay-Signature: t=1758268800,v1=9c1f...,v1=3ea7...
新密鑰 舊密鑰所以你可以在窗口期內任意時刻更新配置，不必和平台同步切換。
輪換前請先確認你的驗簽代碼能處理多個 v1=。只取第一個或用 Object.fromEntries 之類只保留最後一個的寫法，會在窗口期內驗簽全部失敗。Webhook 頁 有三種語言的正確實現。
投遞優先級
| 情況 | 事件發往 |
|---|---|
下單時傳了 notify_url | 只發這個地址，用訂單所屬應用的回調簽名密鑰簽名 |
沒傳 notify_url | 訂單所屬應用的、以及賬戶級的、訂閲了該事件類型的已啓用端點 |
多個端點各自獨立重試，一個端點故障不會拖住其它端點。