跳轉到主要內容

Webhook 亂序:事件到達順序不對時該怎麼處理

Webhook 為什麼會亂序到達、按到達順序處理會出什麼問題,以及在支付接入中安全處理事件順序的四種方法。

發佈於 約 4 分鐘閲讀

手繪插畫:編號 1、2、3 的三個 Webhook 信封按 2、3、1 的順序到達一台服務器,服務器在處理前重新查詢訂單,旁邊一個人雙手插兜
本文目錄
  1. Webhook 為什麼會亂序到達
  2. 按到達順序處理會出什麼問題
  3. 處理亂序 Webhook 的四種方法
  4. 實際中的亂序 Webhook
  5. 補回缺口
  6. 總結

Webhook 可能會亂序到達。後發生的事件可能先到達你的服務器,因為每一次投遞都是一個獨立的 HTTP 請求:一條可能因為超時要稍後重試,而下一條馬上就送達了;或者兩條被你的服務器並發處理。如果你的處理代碼按到達順序應用事件,一條遲到的"處理中"可能會覆蓋"已支付",或者一筆退款會在它所退的那筆付款之前被處理。

這篇文章説明為什麼 Webhook 事件的順序沒有保證、假設它有序時會出什麼問題,以及在支付接入中安全處理亂序 Webhook 的四種方法。

Webhook 為什麼會亂序到達

  • 重試。 失敗或超時的投遞會稍後重試——30 秒後,然後 2 分鐘、10 分鐘、30 分鐘和 2 小時。這期間,同一訂單之後的事件按各自的節奏投遞。
  • 端點相互獨立。 有多個 Webhook 端點時,每個端點獨立重試,所以各自看到的順序也不同。
  • 你自己的並發。 相隔一秒的兩條 Webhook 可能被兩個 worker 處理,第二條可能先處理完。
  • 補回。 之後從事件接口讀回、或者手動重新投遞的事件,會在更新的事件之後很久才到。

所以最多把順序當作提示。每個事件都帶有 created_at——事件發生的時間——但你的代碼不應該依賴事件按這個順序到達。

按到達順序處理會出什麼問題

先到達後到達如果按到達順序應用
refund.succeededpayment.succeeded你為一張還沒標記為已支付的訂單處理退款
payment.succeeded(一條重試的、過時的狀態更新)數據庫裏一張已支付的訂單退回到"處理中"
dispute.wondispute.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 去重;
  • 無論事件以什麼順序到達,每張訂單只履約一次。

在沙箱裏把它跑通

註冊商戶後即可申請測試密鑰,不需要等待資質審核。