定義
Webhook 是由事件發生端主動送出 HTTP 請求的通知機制。當表單送出、付款完成或資料更新時，來源系統把事件名稱與資料送到接收網址，接收端再觸發後續流程。它的核心是事件驅動，而不是由接收端一直詢問。
Webhook 通常使用 HTTPS 與 POST，Payload 可採 JSON。接收端應先做簽章、時間戳與欄位驗證，再快速回覆成功，把寄信、AI 分析或跨系統寫入交給背景工作。事件契約要寫明欄位、版本、唯一識別碼與重試行為，並可搭配 API 補取完整資料。
為什麼中小企業需要了解這個？
Webhook 能把「客戶完成動作」接成「公司開始處理」，適合表單進件、付款通知、預約更新與訊息分派。不過 Webhook 只是通知通道，不會自動解決權限、資料品質、重複事件或下游服務故障。
導入前先確認來源支援哪些事件、是否重試、重試多久，以及接收端要如何回應。若事件包含個資，限制可傳欄位並避免寫入公開日誌；若會修改訂單或 CRM，加入去重與人工待處理清單。可參考 自動化主題 與 AI 自動化服務。
Webhook 與輪詢（polling）的差異
輪詢由接收端依固定週期呼叫 API，優點是流程直觀、可主動補查；缺點是沒有新資料時仍會產生請求，且更新可能要等下一次查詢。Webhook 由來源端推送，延遲通常較低，但必須依賴來源端的可靠重試與事件契約。
| 面向 | Webhook | 輪詢 |
|---|---|---|
| 觸發者 | 事件來源 | 接收端 |
| 沒有事件時 | 不需查詢 | 仍可能發請求 |
| 主要設計 | 驗證、重試、冪等 | 週期、游標、補查 |
| 適合 | 即時通知 | 可補查或無推送能力的服務 |
常見做法是 Webhook 先通知「狀態已變更」，再用 API 取回可信資料；若事件漏接，則用輪詢或人工補查恢復。
安全性與驗證
接收端應使用 HTTPS，並驗證來源提供的簽章、密鑰、時間戳或請求來源。簽章驗證要使用原始請求內容，並設定時間窗避免重放；憑證放在安全的秘密管理機制，不要寫進前端、流程名稱或共用文件。
驗證通過後，只把必要資料送進下游。日誌至少保留事件 ID、類型、結果與錯誤原因，但遮蔽個資與密鑰。對會造成外部副作用的事件，先做格式檢查與狀態判斷，再執行動作；必要時加入人工核准。
常見應用與失敗原因
企業表單送出後，可由 Webhook 驗證資料、建立 CRM 名單、分派負責人與產生回覆草稿；付款、取消或退款則可作為不同事件，依狀態更新系統。流程工具如 n8n、Make 與 Zapier 能協助編排，但仍要先定義事件契約。
常見失敗原因包括接收端逾時、簽章驗證失敗、欄位缺漏、第三方改版、重試造成重複與下游暫停。接收端應快速回覆、設定背景處理、使用事件 ID 去重，並把無法處理的事件送進待處理佇列。更多流程可讀 工作流自動化 與 行政工作自動化。
事件契約應與流程一起版本化。寫清楚事件名稱、Payload 欄位、時間格式、唯一識別碼、簽章規則與版本相容方式，並在供應商改版前安排測試。接收端不要把所有欄位視為永遠存在；對未知欄位採容錯，對必要欄位缺漏則拒絕並留下可追查的錯誤。
維運時把 Webhook 當成可能延遲、重送或失敗的訊息，而不是一次性函式呼叫。建立事件收件紀錄與處理紀錄的關聯，讓人員能查看狀態、補送或標記已處理。若下游工作很慢，先回覆來源端，再由背景工作執行，避免來源端因等待而重試。
事件處理最好分成接收、驗證、排程與執行幾個階段。接收階段只做必要檢查並保存事件狀態；背景工作再依事件類型呼叫 API 或通知服務。這樣能讓接收端維持簡單，也能在下游暫停時保留待處理事件，不必要求來源端無限重送。
設計補償機制時，先確認來源是否提供事件查詢或重送功能；若沒有，就要自行保留必要的事件索引與人工補登方式。測試不只看成功回應，也要模擬網路中斷、簽章錯誤、同一事件多次抵達與欄位增加，確認系統不會重複造成外部副作用。
Webhook 的事件契約怎麼維護？
事件契約要讓來源與接收端對同一個事件有相同理解，至少說明事件名稱、唯一識別、必要欄位、資料型別、簽章方式、版本與重試行為；契約清楚，故障才容易定位。
建立新事件前先用測試 Payload 驗證正常與例外資料，並記錄接收端回應與處理結果。欄位增加時盡量保持向後相容；必要欄位改變或語意改變時，應升級版本並通知所有使用者。維運人員要能查到事件是否收到、是否驗證通過、是否排入背景工作，以及最後是否成功完成，避免只看來源端顯示「已送出」。
Webhook 如何處理事件順序與重複送達？
Webhook 不一定按照事件發生的順序抵達，也可能因來源重試而收到同一事件多次。接收端不能只依抵達時間覆寫資料，應讀取事件 ID、事件時間與資源版本，按照業務規則判斷哪一筆狀態較新。若來源提供序號或游標，應保存最後處理位置；若沒有，則要用資源查詢 API 或人工核對補足判斷依據。
去重紀錄至少要能辨認同一事件，並保留處理中、成功、失敗與已忽略等狀態。收到較舊事件時，不要直接把新狀態改回舊狀態；收到同一事件時，應回傳可接受的結果，但不再次執行寄信、退款或其他外部副作用。對順序敏感的流程，可先把事件放入佇列，依資源鍵分組處理，並為卡住的事件保留人工介入出口。
測試時要刻意交錯送出建立、更新與取消事件，模擬延遲、重複、部分成功和服務重啟。驗收不只看最後畫面正確，也要確認每一筆事件都有可追查的處理紀錄，並能在不重複造成副作用的前提下安全補送。