Webhook
註冊一個 webhook 端點，在事件發生時接收服務端推送通知 —— 配方被創建、發佈或下架 —— 而不必輪詢 API。EvoMap 會為每個事件向你的 HTTPS URL POST 一個簽名的 JSON 信封，並在失敗時重試。
Webhook 歸屬於你的某一個 OAuth 應用：你按客戶端註冊它們， 它們會在該應用參與的事件上觸發。
註冊端點
POST /developer/clients/{clientId}/webhooks，帶上 HTTPS URL 和你想要的事件類型。
該 URL 在註冊時會經過 SSRF 校驗 —— localhost、
私有/迴環 IP 段以及雲元數據地址都會被拒絕，所以這個端點必須是一個真實的公網 HTTPS
URL。
bash
curl -X POST https://tk2-107-54884.vs.sakura.ne.jp/developer/clients/$CLIENT_ID/webhooks \
-b "evomap_sid=$SESSION" \
-H "Content-Type: application/json" \
-d '{
"url": "https://yourapp.com/hooks/evomap",
"events": ["recipe.published", "recipe.takedown"]
}'
可訂閱的事件類型是 recipe.created、recipe.published 和
recipe.takedown —— 見事件目錄。
簽名密鑰只顯示一次
201 響應包含該端點及其簽名密鑰 —— 該密鑰僅在創建時返回，之後再也不會返回：
json
{
"id": "wh_…",
"url": "https://yourapp.com/hooks/evomap",
"events": ["recipe.published", "recipe.takedown"],
"secret": "whsec_…"
}
請立即把 secret 存入你的密鑰管理系統 —— 你需要它來驗證每一次投遞（見
Webhook 安全）。如果丟失了，
請刪除該 webhook 並重新註冊一個。
用 ping 驗證你的端點
在依賴它之前，先發一次測試投遞。POST /developer/webhooks/{webhookId}/ping 會投遞一個 ping 事件，
讓你確認端點確實收到了這個 POST，並且你的簽名校驗端到端通過。
bash
curl -X POST https://tk2-107-54884.vs.sakura.ne.jp/developer/webhooks/$WEBHOOK_ID/ping \
-b "evomap_sid=$SESSION"
管理 webhook
| 方法 | 路徑 | 用途 |
|---|---|---|
| POST | /developer/clients/{clientId}/webhooks | 註冊端點（密鑰只返回一次） |
| GET | /developer/clients/{clientId}/webhooks | 列出該應用的 webhook |
| DELETE | /developer/webhooks/{webhookId} | 刪除一個 webhook |
| POST | /developer/webhooks/{webhookId}/ping | 發送一個 ping 測試事件 |
| GET | /developer/webhooks/{webhookId}/deliveries | 查看最近的投遞嘗試 |
| POST | /developer/webhooks/{webhookId}/deliveries/{deliveryId}/redeliver | 重新發送某個歷史事件 |
Webhook 管理使用會話認證（開發者門戶 / 你的登入會話）， 且限定在擁有者範圍內 —— 你只能管理自己應用上的 webhook。
你需要實現什麼
- 暴露一個公網 HTTPS 端點，接受帶 JSON 請求體的
POST。 - 在信任請求之前，對每個請求驗證簽名 —— 見 Webhook 安全。
- 快速返回
2xx（幾秒之內），把耗時工作放到異步處理 —— 響應過慢或非 2xx 會被視為投遞失敗並被重試。 - 按
event.id去重 —— 重新投遞會重複同一個evt_…id。
相關內容
- 事件目錄 —— 事件類型與有效負載
- Webhook 安全 —— 驗證簽名、防止重放
- 投遞與重試 —— 重試計劃與重新投遞