Webhook 亂序:事件到達順序不對時該怎麼處理
Webhook 為什麼會亂序到達、按到達順序處理會出什麼問題,以及在支付接入中安全處理事件順序的四種方法。
Webhook 可能會亂序到達。後發生的事件可能先到達你的服務器,因為每一次投遞都是一個獨立的 HTTP 請求:一條可能因為超時要稍後重試,而下一條馬上就送達了;或者兩條被你的服務器並發處理。如果你的處理代碼按到達順序應用事件,一條遲到的"處理中"可能會覆蓋"已支付",或者一筆退款會在它所退的那筆付款之前被處理。
這篇文章説明為什麼 Webhook 事件的順序沒有保證、假設它有序時會出什麼問題,以及在支付接入中安全處理亂序 Webhook 的四種方法。
Webhook 為什麼會亂序到達
- 重試。 失敗或超時的投遞會稍後重試——30 秒後,然後 2 分鐘、10 分鐘、30 分鐘和 2 小時。這期間,同一訂單之後的事件按各自的節奏投遞。
- 端點相互獨立。 有多個 Webhook 端點時,每個端點獨立重試,所以各自看到的順序也不同。
- 你自己的並發。 相隔一秒的兩條 Webhook 可能被兩個 worker 處理,第二條可能先處理完。
- 補回。 之後從事件接口讀回、或者手動重新投遞的事件,會在更新的事件之後很久才到。
所以最多把順序當作提示。每個事件都帶有 created_at——事件發生的時間——但你的代碼不應該依賴事件按這個順序到達。
按到達順序處理會出什麼問題
| 先到達 | 後到達 | 如果按到達順序應用 |
|---|---|---|
refund.succeeded | payment.succeeded | 你為一張還沒標記為已支付的訂單處理退款 |
payment.succeeded | (一條重試的、過時的狀態更新) | 數據庫裏一張已支付的訂單退回到"處理中" |
dispute.won | dispute.created | 已經結案的拒付被重新打開 |
處理亂序 Webhook 的四種方法
1. 讓狀態只能單向流轉
把訂單狀態建模成狀態機,並拒絕倒退:一旦 paid,任何支付事件都不能讓它回到 pending。KukoPay 自己的狀態就是這樣:訂單從 pending 變為 paid、expired 或 failed,已支付的訂單只會繼續變為 partially_refunded 或 refunded。如果你的表也這樣設計,過時的事件就不會產生任何效果。
2. 讀取當前狀態,而不是相信事件
事件的 data.object 是事件發生那一刻對象的快照。當事件順序很重要時,請改為讀取當前狀態:
curl "https://api.kukopay.com/v1/orders/ORD_20261117_0001" \
-H "X-Api-Key: $KUKOPAY_API_KEY"把 Webhook 當作"有變化了"的信號,把訂單查詢當作"現在是什麼樣"的答案。退款(GET /v1/refunds/{refund_no})和拒付也一樣。每條 Webhook 多一次讀請求,遠在讀接口的頻率限制之內,見 API 調用頻率限制。
3. 覆蓋之前先比較時間戳
如果你根據事件保存狀態,就把事件的 created_at 一併保存,對於比你已有記錄更舊的事件直接忽略。在負擔不起一次查詢時,這是防止過時更新最省事的辦法。
4. 按事件 id 去重
亂序和重複總是一起出現:一條重試的事件可能在你處理過之後才到。在狀態變更的同一個事務裏,把每個事件 id 寫入帶唯一約束的表,見過的 id 直接跳過,見 支付回調冪等處理。
實際中的亂序 Webhook
- 退款先於付款。 如果收到
refund.succeeded時,你的記錄裏這張訂單還是未支付,就查一下訂單:它是refunded或partially_refunded,説明它之前已經支付過。兩件事都要記錄。 - 拒付事件。
dispute.created→dispute.updated→dispute.won、dispute.lost或dispute.closed。一旦拿到最終結果,就忽略任何更早的事件——或者讀取GET /v1/disputes/{dispute_no}。 - 先失敗或過期,後來又支付了? 不會發生。銀行卡被拒不是一個事件——訂單保持
pending,買家可以重試——而payment.failed/payment.expired表示訂單已經關閉。訂單關閉後仍然到達的付款會全額退回買家,並以payment.duplicate_refunded通知,而不會是payment.succeeded,見 重複扣款怎麼辦。 - 只履約一次。 無論事件以什麼順序到達,都在看到某張訂單的第一條
payment.succeeded時發貨,之後不再重複。
補回缺口
如果懷疑漏了事件——端點宕機過,或者一次發佈丟了一些——就按時間窗口從事件接口列出它們(按時間倒序),用同樣的規則處理:去重、拒絕倒退的狀態變化、拿不準時查詢當前狀態。見 收不到 Webhook 怎麼辦。
總結
- Webhook 可能因為重試、端點相互獨立、你自己的並發以及之後的補回而亂序到達;
- 永遠不要讓到達順序決定狀態:讓狀態只能單向流轉,拒絕讓已支付的訂單倒退;
- 當順序很重要時,把 Webhook 當作信號,從 API 讀取對象的當前狀態;
- 保存
created_at以忽略過時事件,並在狀態變更的同一個事務裏按事件id去重; - 無論事件以什麼順序到達,每張訂單只履約一次。
在沙箱裏把它跑通
註冊商戶後即可申請測試密鑰,不需要等待資質審核。