Webhook
Webhook
什麼是 Webhook?
- 事件發生時,伺服器先通知
- '反向 API'
- 適合用於即時串接
導入 Webhook 後,做事的主體會改變。在輪詢方式下,我們的伺服器每 1 分鐘就會敲一次金流公司的 API,詢問'有沒有新的付款?'。即使一天問 1,440 次,真正有收穫的通常只有幾十筆,其餘全是空查詢。改用 Webhook 後,這些白問的動作會消失,從事件發生到處理完成,由分鐘級縮短到秒級,而原本消耗 API 呼叫配額的空查詢整個消失,伺服器成本與故障點也一併減少。
接上之前要檢查的項目是簽章驗證、回應速度、重試與冪等處理四項。大多數服務會在請求標頭中附上 HMAC 簽章,所以必須用密鑰比對,過濾掉偽造的請求;接收端通常需要在 3~5 秒內回傳 200 OK。庫存扣除或寄送郵件等較重的工作,最好放進佇列,先回應再處理,這是標準做法。若處理失敗,提供方通常會以數分鐘到數小時的間隔重送數次,因此要確保同一個事件 ID 即使送達兩次,訂單也只會被記錄一次。
和其他相似的工具先劃清界線,設計時會比較容易。一般 API 是我們需要時才取用的窗口,但 Webhook 是對方丟出一次就結束的通知,接收當下若無法處理,就會直接流失。若目的是即時更新畫面,適合用 SSE 或 WebSocket;若要每天依序累積數十萬筆事件,則適合 Kafka、SQS 等訊息佇列。Webhook 最適合處理「每天數千筆等級的事件傳遞」,是最合適的中介工具。
現場最常出錯的,是「Webhook 只會送一次,而且會依送出順序抵達」這個預設想法。因重送與網路狀況,同一筆付款完成通知可能收到兩次,結果訂單多出兩筆、庫存被扣兩次,這類事故確實會發生。內部防火牆後方設有接收伺服器,開發環境收得到的通知,到正式環境一筆也收不到的情況也很常見。請以「偶爾會遺失的通知」為前提來設計 Webhook,涉及金錢的事件,則應另外每天執行一次帳務對帳(重新查詢)批次,才能抓出夜間遺漏的紀錄。
此用語於 2007 年由 Jeff Lindsay 提出,之後廣泛用來指稱「事件發生時自動傳送資料」的網路整合方式。
以下以虛構案例來說明。這是一家擁有全體員工 52 人、年營收規模為 KRW 1,800,000,000 (≈ US$1,347,200) 的自家商城營運公司「A 公司」的故事。他們每 5 分鐘以批次方式確認付款是否完成,結果訂單送到物流倉庫平均要花 7 分鐘;'已經付款了,為什麼還在處理中?'這類客服詢問,每週湧入 40 件。開發團隊 4 人花了 3 週,投入付款 Webhook 的轉換工作。
- 開發組長 Kim 次長在第一次會議上整理出 "不要每 5 分鐘去問,改由金流公司先通知我們吧",並在 PG 業者的管理後台登錄了接收網址。
- 後端負責人 Lee 代理加入 HMAC 簽章比對邏輯,並用 20 筆測試付款進行測試,結果確認簽章不符的偽造請求 2 筆確實被擋下。
- 上線第二天,同一筆付款事件連續 3 次進來,導致訂單重複建立。Lee 代理於是把 event_id 設為資料庫的唯一鍵,從第二次開始只回傳 200 OK、直接忽略。
- 回應超過 6 秒,逾時失敗率升到 4%,於是把庫存扣除與寄送通知信的工作移到佇列處理,收到請求後立即回應,把失敗率降到 0.2%。
- 轉換後 3 週,從訂單到出貨指示的平均時間由 7 分鐘縮短為 12 秒,客服詢問每週從 40 件降到 6 件,原本每天 8,640 次的輪詢呼叫則降為 0 次。
朴雪英
金鍾赫