Webhook 是什麼？API 差異、失敗處理與串接驗收

Webhook 是事件發生後，來源系統主動把通知送到指定網址的機制。例如訂單狀態改變時，來源服務通知另一套系統接續處理。收到通知與完成業務動作是兩件事，因此串接規格還要寫清楚驗證、重複事件、失敗補送與查核責任。

這篇從企業委外串接的角度，說明 Webhook 與查詢 API 的分工，並提供測試情境。以下訂單與付款例子是假設流程，不代表即站力已支援每一家支付、庫存或發票服務，實作前仍要確認雙方官方介面與授權。

Webhook 和 API 有什麼差別？

可以把 Webhook 理解成有事件時送來的通知，查詢 API 則是你主動詢問某筆資料。兩者可以搭配：先由事件通知啟動工作，再依權限查詢正式資料。這不表示所有 API 都要定時輪詢，也不表示收到通知就能直接完成交易。GitHub 的 Webhook 說明可作為事件通知模式的原始參考。

比較項目	Webhook 事件通知	主動呼叫查詢 API
啟動時機	來源服務發出已訂閱的事件	接收端依流程需要提出查詢
需要準備	接收網址、驗證與事件處理	授權、查詢條件與回應處理
失敗時要確認	送達紀錄、補送方式與重複處理	錯誤回應、重試規則與查詢限制
常見搭配	通知到達後啟動查核	取得當下可用的正式資料

串接前，先把三種責任寫清楚

來源服務負責什麼事件與資料，接收系統如何驗證與處理，營運人員又從哪裡查到結果，應在開發前分開確認。若只是接到通知就寄出貨信，卻沒有確認對應訂單與付款狀態，流程可能把「通知存在」誤認為「交易完成」。

假設是付款後更新訂單的流程，規格要寫明事件如何對應本地訂單，哪些狀態允許更新，以及查不到訂單或金額不符時如何隔離處理。第三方資料欄位、重試次數與時限一律以該服務正式規格為準，不把另一家平台的規則直接照搬。

Webhook URL 要準備什麼？

Webhook URL 是接收事件的端點網址，不是會員登入頁或商品頁。先確認來源服務能連到它，使用有效的 HTTPS，並依官方規格驗證通知來源與內容；憑證或密鑰不應直接放進容易被記錄與分享的網址。GitHub 的Webhook 最佳做法有相關安全與處理建議，其特定回應時限不能當成所有平台共同標準。

密鑰由指定人員保管並規劃輪替，日誌只留排查需要的資訊，避免把完整個資或憑證貼進客服訊息。若要接 LINE，請回到LINE API 串接指南確認 Channel 與官方帳號的設定脈絡；不同平台的驗證方式可能不同。

重複、延遲或漏掉通知時怎麼辦？

企業應把這些情境列入驗收，具體處理則依來源服務能力設計。所謂冪等，就是相同事件重複處理時，不多產生一次相同的業務結果，例如不重複建立出貨單。可使用服務提供的事件識別碼與業務狀態核對，但不能只用通知到達的時間判斷唯一性。

如果事件延遲或順序不同，接收端要避免把已完成的狀態倒退更新；如果通知沒有送達，則確認是否能補送，或由查詢與人工對帳補足。補送與狀態查詢是否可用，要逐一查證服務規格，不承諾每家平台都有自動重試。

Webhook 串接驗收，至少測到哪些情境？

測試情境	要核對的結果
正常事件	正確對應資料，完成預期動作並留下紀錄
相同事件再次送出	不重複出貨、寄送或建立單據
驗證失敗或資料不符	拒絕或隔離，能追查原因，不更新交易
接收端暫時不可用	依來源規格測試失敗紀錄與補救
事件延遲或順序改變	不把新狀態覆蓋成過期狀態
人工補送與查核	有權限的人可確認最終業務結果

測試時保存事件識別、處理時間、結果與失敗原因，並分開記錄「HTTP 已回應」與「業務已完成」。若使用背景佇列，收到成功回應後仍可能有後續處理失敗，不能只憑狀態碼驗收。完整範圍可以連到系統開發驗收清單。

把事件規則寫進需求，再評估串接

先整理來源服務、事件名稱、資料對應、授權人、例外流程與驗收情境，再交給開發團隊評估。文件可依需求規格書指南整理，跨系統的資料責任則看API 串接指南。需求已明確時，可由即站力系統開發服務進一步確認可行性與範圍。

重點整理

Webhook 就是一般的查詢 API 嗎？

Webhook 是事件發生後主動送到接收網址的通知，查詢 API 是主動詢問資料。兩者可搭配，不能把所有 API 都視為定時輪詢。

Webhook 回傳成功，就代表訂單更新完成嗎？

不一定。若有後續背景處理，成功回應可能只代表已接收，仍要核對最終業務狀態與錯誤紀錄。

每個 Webhook 服務都會自動重試嗎？

不能一概而論。重試、補送與狀態查詢能力，要依來源服務的正式規格查證，並安排失敗測試與人工查核路徑。