Skip to main content
首頁博客指南如何透過定期 API 輪詢彌補遺漏的 Webhook 更新:混合式同步實戰指南

如何透過定期 API 輪詢彌補遺漏的 Webhook 更新:混合式同步實戰指南

17TRACK

使用 webhooks 接收提示更新,並定期輪詢 API,以檢查本地貨件記錄是否仍與供應商記錄一致。可靠的做法是持久儲存 webhook 交付內容,使用穩定的貨件識別碼與 API 進行核對,並透過相同的冪等更新邏輯處理這兩條路徑。輪詢可以修復遺漏的狀態變更,但除非 API 實際提供事件歷史,否則無法重建中間事件。

如何透過定期 API 輪詢核對遺漏的 Webhook 更新

本指南適用於負責讓訂單管理系統、追蹤頁面或客戶支援檢視與貨件資料保持同步的工程師及營運團隊。其核心規則很簡單:將 webhook 視為檢查及處理變更的訊號,而不是每一項較早的變更都已送達的證明。

選擇間隔前,先定義「同步」的含義

貨件整合可能需要保留兩種不同的資料:目前狀態,例如「運輸中」或「已送達」;以及說明貨件如何到達目前狀態的事件歷史。供應商的貨件查詢可能只返回最新狀態、追蹤事件清單,或兩者皆有。這些 API 形式會帶來不同的復原保障。

如果查詢只返回目前狀態快照,核對輪詢可以在 webhook 遺漏後修正本地狀態,但無法證明曾經出現哪些中間狀態。如果 API 返回帶有穩定識別碼或時間戳記的歷史事件,輪詢也可能恢復遺漏的時間軸項目。在向下游使用者承諾任何一種結果前,請先檢查供應商實際的回應結構。

列出應用程式必須核對的欄位:貨件識別碼、承運商或追蹤識別碼、標準化狀態、供應商狀態、事件時間、供應商最後更新時間、配送詳情,以及任何用於觸發客戶訊息的欄位。將由供應商負責的權威欄位,與本地擁有的欄位分開,例如內部個案備註。核對工作不應僅因某欄位未出現在 API 回應中,就覆寫只屬於本地的資料。

為 webhook 與輪詢結果建立單一處理流程

Webhook 處理器與輪詢工作程式不應各自實作互相競爭的狀態變更規則。兩者都應產生標準化觀察結果,並將其交給同一個核對函式。該函式會驗證身份、將觀察結果與已儲存的貨件進行比較、寫入安全更新,並記錄作出變更的原因。

  1. 接收及驗證身份。 使用供應商記錄的機制驗證 webhook。拒絕驗證失敗的請求,但保留足夠的非敏感診斷資料,以便調查交付問題。
  2. 確認後再持久儲存。 在返回成功前,先將有效交付內容放入持久儲存或佇列。若在持久儲存前便發出成功的 HTTP 回應,會產生供應商重試也未必能修復的缺口。
  3. 標準化。 將供應商 payload 或 API 回應映射至通用的內部結構,同時保留原始供應商值,以便調查。
  4. 核對。 使用穩定的貨件鍵及冪等規則,防止重複的時間軸項目、重複通知及不必要的寫入。
  5. 記錄結果。 記錄觀察結果是否變更貨件、是否已知悉、是否早於已儲存狀態,或是否需要人工審查。

如果供應商事件 ID 存在且穩定,便可用於去重。如果不存在,可能需要組合鍵,但其組成部分必須符合供應商的資料模型。兩次有效掃描可能共用相同的狀態及時間戳記,因此僅由這些欄位組成的鍵可能會錯誤捨棄真實事件。保留原始 payload 或其參考資料一段明確定義的保存期限,以便調查模糊匹配。

以風險而非單一全域計時器設計輪詢循環

以相同頻率輪詢所有已知貨件會浪費請求,亦可能對 API 限額造成壓力。維護一組符合核對條件的貨件,並根據營運風險選擇它們。剛登記但尚未收到首次更新的貨件、最近 webhook 處理失敗的貨件,以及在預期流程內狀態長時間沒有變更的貨件,可能需要不同的排程。已完成的貨件可能只需要有限的最後檢查,具體取決於延遲修正對應用程式是否重要。

由企業可容忍本地狀態錯誤的最長時間倒推輪詢間隔。計算佇列延遲、請求時間、重試及工作程式容量;輪詢間隔本身並不等於復原時間。加入抖動,避免大量貨件在同一時間到期。如果供應商記錄了請求限制或提供批次查詢,應將這些限制納入設計,而不是假設在小型測試中可行的設計能夠原樣擴展。

將排程器的記錄與供應商狀態分開。last_poll_attempt_at、last_successful_poll_at、next_poll_at 及 last_webhook_received_at 等欄位回答的是不同問題。尤其是,逾時的輪詢嘗試不得更新成功輪詢標記。

當 API 支援條件請求、已記錄的變更游標或 updated-since 篩選器時,應評估它是否能在不隱藏記錄的情況下減少不必要的傳輸。HTTP 定義了條件請求行為,包括 304 Not Modified 回應,但整合只應在相關端點支援且其語義清晰時使用。游標不能與時間戳記互換:請確認其排序依據、是否限定於帳戶或貨件,以及分頁返回結果時的行為。

核對時不要回滾較新的更新

最常見的競態情況很直接:輪詢開始後,較新的 webhook 到達,而輪詢返回較舊的快照。如果未比較便最後寫入輪詢結果,本地貨件便會倒退。若供應商事件時間或版本可靠,應檢查該資料,並確保每件貨件的比較及寫入是原子操作。

不要假設到達時間反映事件順序。延遲交付的 webhook 可能描述較早的掃描,而較後的 API 回應可能包含對先前報告事件的修正。為時間軸插入及目前狀態選擇定義獨立規則。例如,舊掃描可以保留在歷史中,但不取代目前狀態。供應商修正可能需要修改已儲存事件,而不是新增另一項。正確規則取決於供應商提供哪些識別碼、時間戳記及修訂訊號。

如果供應商沒有可靠的版本或排序欄位,應採取保守做法。將完整返回記錄與本地記錄比較,標記矛盾,並避免將狀態標籤視為通用排序方案。「異常」、「派送中」及「已送達」並不總是構成簡單的線性順序,尤其是承運商稍後修正掃描時。將供應商原始值與任何標準化狀態一併保留,以便人工檢視不確定個案。

副作用也需要採用與儲存相同的規範。若輪詢發現「已送達」,而 webhook 已經觸發過一次通知,輪詢不應再次發送送達通知。讓通知及下游工作根據持久化業務鍵實現冪等,例如貨件識別碼加上已定義的狀態轉換或供應商事件 ID。資料庫更新及外部通知通常不能視為單一自動操作;交易式 outbox 或等效的持久工作記錄,有助於確保已提交的變更只會以受控方式嘗試處理一次副作用。

中斷後執行有界回填

例行輪詢不能取代明確的復原程序。當 webhook 端點、佇列或工作程式不可用時,首先找出受影響的期間及貨件集合。應包括中斷期間處於活躍狀態的貨件,而不只是目前標記為活躍的貨件:有些貨件可能在更新遺漏期間已到達終端狀態。

回填開始時間應提前至疑似故障之前,以考慮延遲交付及偵測時間的不確定性。這種重疊會有意重新處理部分已知資料;冪等性使其比留下缺口更安全。以可管理的批次處理結果,持久記錄進度,並保留失敗項目以便重試。不要僅因已請求某一頁,就推進回填檢查點。只有在該頁記錄已處理或已明確記錄為未解決後,才可推進檢查點。

如果 API 提供分頁,請先確認其排序及延續行為,再使用頁碼或游標作為復原檢查點。如果 API 只提供每件貨件的快照,則從自己的記錄建立受影響貨件清單,並逐一核對。記錄這種方法的限制:最終目前狀態可能正確,但部分中間掃描仍然無法取得。

測試預期需要修復的故障情況

有用的測試計劃不應只發送一個 webhook 再檢查一個 API 回應。應測試重複的 webhook 交付、較新的 webhook 之後才到達的舊 webhook、在 webhook 之後才到達的輪詢回應、部分 API 失敗、工作程式重啟,以及儲存貨件狀態與排程通知之間發生崩潰。請同時驗證可見的貨件記錄及副作用記錄。

亦應測試包含多於單一批次容量記錄的中斷回填。確認重新啟動工作時會安全地重複少量工作,而不是跳過記錄。若 API 返回歷史事件,測試同一掃描是否會同時以 webhook 及輪詢格式出現,以及去重規則能否識別它。若 API 只返回快照,確認介面不會將推斷出的中間事件呈現為已觀察到的承運商掃描。

營運監控應區分三種訊號:webhook 交付健康狀況、輪詢健康狀況及資料新鮮度。有用的指標包括符合條件貨件最後一次成功核對的時間、未解決不匹配的數量、佇列年齡、API 錯誤率及復原積壓的大小。健康的 webhook 端點本身並不能證明本地貨件狀態是最新的。

將本指南應用於追蹤 API

對於貨件追蹤整合,應從供應商記錄的識別碼、webhook payload、貨件查詢回應、驗證要求及請求限制開始。如果使用 17TRACK’s Tracking API,請在實作輪詢器前參閱其官方 API 文件。確認整合可用的查詢及更新機制,不要假設每個帳戶或端點都支援歷史重播、基於游標的回填或條件請求。

實作上的選擇並不是「webhooks 或輪詢」。使用 webhooks 降低一般更新延遲,使用輪詢偵測及修復可用 API 能揭示的不一致,並為事故建立明確的回填程序。在操作手冊中說明復原界線:系統能否恢復目前狀態、事件歷史,還是兩者皆可。這條界線決定遺漏的更新會造成短暫的過時檢視,還是令記錄永久出現缺口。

常見問題

輪詢可以保證不會遺漏追蹤事件嗎?

不可以。目前狀態查詢可以顯示最新狀態已變更,但無法恢復 API 不返回的中間事件。恢復歷史事件需要可用的事件歷史,以及可靠地識別或比較其項目的方法。

Webhook 是否應觸發即時 API 輪詢?

只有在 API 查詢能提供應用程式需要的額外資料,或 webhook 有意只作為變更通知而非完整記錄時才需要。每個 webhook 後都輪詢可能產生重複請求。如果 webhook 包含足夠可靠的資料,應直接處理,並將 API 檢查留給排程核對或針對性調查。

如果 API 輪詢與 webhook 不一致,應怎樣處理?

在選擇目前狀態前,先比較兩者的供應商時間戳記、版本、識別碼及 payload 含義。保留兩項觀察結果。如果供應商沒有可靠的排序訊號,而不一致會影響重要操作,應將貨件標記為需要檢視,而不是默默選擇最後到達的回應。

已送達貨件何時應停止輪詢?

根據延遲的承運商修正、送達證明詳情或下游流程對應用程式是否重要,採用已記錄的政策。僅有看似終端的狀態,並不能證明供應商之後永遠不會再更新記錄。

輪詢器應如何處理速率限制?

降低請求壓力,使用退避策略重試,並在伺服器提供 Retry-After 標頭時遵守它。優先處理最需要復原的貨件,而不是同時反覆重試所有貨件。HTTP 語義定義了 429 Too Many Requests 回應及 Retry-After 欄位;端點特定的限制仍需查閱供應商文件。

來源