Webhook

Webhook 是用於接收事件通知的 HTTP 端點。當特定事件發生時，系統會主動向預先定義的 URL（Webhook URL）傳送 HTTP 請求。Webhook 通常用於通知外部系統狀態變更或非同步任務結果。

常見使用情境

雖然從技術上來說，Webhook 只是一個 HTTP 端點，但它的使用方式有所不同：

Webhook：系統主動呼叫外部 URL

一般端點：用戶端向系統傳送請求

在你的 Apidog 專案中，點擊左側側邊欄的 "+" 圖示，並選擇 "New Other Protocol APIs" → "Webhook"。

建立 Webhook 後，請在編輯器中填寫以下欄位：

欄位	說明
請求方法	通常為 `POST`
Webhook 名稱	顯示於 API 文件和 OpenAPI 匯出中（例如 `order`）
偵錯 URL	選填。用於傳送測試請求的實際 URL（僅供測試使用，不會包含在文件中）
其他資訊	請求主體、標頭和其他設定

完成所有必填欄位後，點擊 "Save"。

Webhook 偵錯會模擬事件觸發，以驗證外部服務是否能正確接收請求。

若要偵錯 Webhook：

將你的 Webhook URL 輸入到 Debug URL 欄位

點擊 "Send" 以模擬 Webhook 呼叫

Webhook 文件包含 Webhook 名稱、請求方法和請求主體等詳細資訊。這能讓使用者更容易了解當特定事件發生時，會傳送哪種類型的資料。

Debug URL 隱私

Debug URL 不會包含在文件或 OpenAPI 匯出中 — 它僅供內部測試使用。

在匯出的 OpenAPI 檔案中，Webhook 端點會列在 webhooks 欄位下，這不同於一般端點的 paths 欄位。

為什麼要在文件中分開定義 Webhook？

根據 OpenAPI 3.1 規範：

一般端點定義在 paths 欄位下

Webhook 端點定義在 webhooks 欄位下

這種清楚的區分可確保：

一般端點由外部用戶端呼叫，用於執行動作或擷取資料

Webhook 由系統觸發，用於通知外部服務

在 Apidog 中，Webhook 會被視為一種獨立的端點類型，以準確反映這種方向性的差異，並確保 OpenAPI 匯出時格式正確。

範例：

/orders 是供用戶端使用的一般端點

orderPaid 是在訂單成功付款時由系統觸發的 Webhook

Webhook 只是一個一般端點嗎？

Debug URL 會顯示在我的 API 文件中嗎？