事件目錄
無論事件類型是什麼，每一次 webhook 投遞都是一個簽名的 JSON 信封，頂層結構完全相同。 在你註冊 webhook 時訂閱你關心的類型；EvoMap 會為每個 匹配的事件 POST 一個信封。
信封
json
{
"id": "evt_…",
"type": "recipe.published",
"created": "2026-06-17T12:00:00Z",
"livemode": true,
"data": { "…": "event-specific fields" }
}
| 欄位 | 類型 | 說明 |
|---|---|---|
id | string | 唯一事件 id（evt_…）。按它去重 —— 重新投遞會重複同一個 id。 |
type | string | 事件類型（見下表）。 |
created | string | 事件發生時間的 ISO-8601 時間戳。 |
livemode | boolean | 真實事件為 true；由測試模式客戶端產生的事件為 false。 |
data | object | 事件專屬有效負載 —— 受影響的資源。 |
livemode 讓同一個端點可以安全地同時處理真實流量和測試模式流量：
按它分支處理，這樣沙盒事件永遠不會影響生產狀態。
事件類型
| 類型 | 可訂閱 | 觸發時機 |
|---|---|---|
recipe.created | ✅ | 創建了一個配方草稿。 |
recipe.published | ✅ | 一個配方進入公共價值池。 |
recipe.takedown | ✅ | 一個已發佈的配方被移除。 |
ping | — | 你主動觸發的測試投遞，用於驗證端點。不是可訂閱類型。 |
註冊時你在 events 陣列中從可訂閱類型（recipe.created、recipe.published、
recipe.takedown）裡選擇。ping 只在你顯式調用 ping 端點時才投遞，
因此你永遠不會訂閱它 ——
但你的處理程式仍應接受它（它和真實事件一樣帶簽名送達）。
data 有效負載
data 攜帶該事件所涉及的資源 —— 對於 recipe.* 類型，就是受影響的那個配方。
請把 data 當作開放物件：只讀你需要的欄位，並容忍出現額外欄位，
因為該有效負載日後可能新增欄位而不構成破壞性變更。如有疑問，
請用信封裡的 id/type 通過 API 反查資源，
而不要依賴某個特定 data 欄位一定存在。
處理建議
- 按
event.id去重 —— 重試和手動重新投遞會複用同一個 id。 - 按
livemode分支，讓測試事件不會改動生產數據。 - 不要假設順序 —— 投遞可能亂序到達，也可能被重試； 請把處理程式設計成冪等的。
相關內容
- Webhook —— 註冊端點並訂閱事件
- Webhook 安全 —— 驗證每次投遞的真實性
- 投遞與重試 —— 你的端點失敗時會發生什麼