Webhook 貨件追蹤：追蹤 Webhook 如何運作與輪詢的比較（Payload、重試及設定）

貨件追蹤 Webhook 會在追蹤服務有更新需要報告時，向你的應用程式發送 HTTP 請求。輪詢則方向相反：你的應用程式會重複請求最新的追蹤資訊。對於需要將貨件資料連接至訂單管理系統、商店或客戶通知服務的開發者而言，在支援的情況下，Webhook 通常是較佳的主要更新機制；針對性的輪詢則有助於恢復遺漏的更新及核對記錄。

這兩種方法都不會令承運商更快掃描包裹。兩者都取決於追蹤來源何時接收並公開新資訊。實際差異在於你的應用程式如何獲取該資訊、產生多少請求流量，以及傳送失敗時會發生甚麼。

追蹤 Webhook 與輪詢：運作上的差異

這些是整合模式，而不是互相競爭的追蹤資料庫。承運商或追蹤平台可能提供其中一種或兩種模式，並附有不同的使用條件。請比較你計劃使用的特定 API 的行為，不要假設所有 Webhook 服務都提供相同的保證。

在以下情況優先選用 Webhook：即時更新很重要，而且你的團隊能夠運作可靠的接收器。在以下情況優先選用輪詢：入站端點不切實際、貨件數量不多，或來源沒有提供合適的 Webhook。在以下情況使用混合設計：遺漏更新會干擾客戶溝通或營運，而 API 支援核對。

不要假設 Webhook 成本較低。訂閱費、追蹤登記、API 呼叫、事件傳送及基礎設施可能按不同方式收費。請比較實際商業條款及預期工作量，不要將較少請求視為帳單較低的證明。

從承運商掃描到你的應用程式之間會發生甚麼？

1. 識別貨件。關聯追蹤號碼、所需的承運商資料及內部貨件參考編號。部分服務要求在開始監控前先進行登記。
2. 設定事件傳送。提供 HTTPS 回呼 URL，並選取任何受支援的事件訂閱。
3. 來源接收追蹤資訊。承運商掃描或狀態變更會在追蹤服務中變得可用。
4. 服務發送 Webhook。請求可能包含完整追蹤快照、單一檢查點，或只包含需要透過 API 查詢的參考資料。
5. 你的接收器驗證並儲存資料。驗證請求、檢查其結構，並持久記錄或將事件加入佇列。
6. 工作程序更新業務系統。標準化狀態、更新貨件記錄，並只觸發仍然適用的操作。

Webhook 傳送與實體配送並不相同。它是有關貨件資訊的訊息。同樣地，成功的 Webhook 回應並不能證明電子郵件已經發送，或訂單記錄已經更新；這些都是需要獨立監控的下游處理結果。

閱讀追蹤 Webhook 負載

以下 JSON 是說明性的整合設計，不是 17TRACK 負載，也不是通用結構。實際欄位名稱、狀態代碼、時間戳格式及事件識別碼必須以所選服務提供者的文件為準。

{
  "event_id": "evt_example_001",
  "event_type": "shipment.updated",
  "created_at": "2025-04-08T10:16:00Z",
  "shipment": {
    "reference": "shipment_example_123",
    "tracking_number": "EXAMPLE123456",
    "carrier_code": "example_carrier",
    "status": "in_transit",
    "checkpoint": {
      "occurred_at": "2025-04-08T10:10:00Z",
      "description": "Departed processing facility"
    }
  }
}

在你的資料模型中分開記錄三個時間：貨件事件發生的時間、服務提供者產生訊息的時間，以及你的應用程式接收訊息的時間。延遲的檢查點可能會在較新的檢查點之後才到達。沒有偏移量的時間戳也需要明確解讀；不要將每個承運商當地時間戳都默默視為 UTC。

保留你的內部貨件參考編號及服務提供者的識別碼。單靠追蹤號碼可能不足以作為永久的全球識別碼，尤其是在不同承運商情境下。對於拆單訂單，請維護貨件層級的記錄，不要讓其中一個包裹的已送達狀態將整張訂單標記為已完成。

在標準化業務狀態旁保留原始狀態及描述。你的應用程式可能會將多個承運商訊息映射至「運送中」，但支援人員仍可能需要原始檢查點來了解延誤。將預計送達日期視為估算值，並區分欄位缺失與明確要求清除現有值的指示。

重試、確認及重複事件

Webhook 傳送可能因逾時、網絡中斷、驗證錯誤或接收器無法使用而失敗。服務提供者可能會重試，但並不存在通用的重試時間表、保留期限或最大嘗試次數。請確認哪些回應會觸發再次嘗試、如何處理重新導向，以及是否提供手動重新傳送功能。

持久接受後再確認

保持請求路徑簡短：驗證請求、保存已接受的工作，並返回服務提供者要求的成功回應。以非同步方式發送電子郵件及執行較慢的業務操作。HTTP 規範將 202 Accepted 定義為接受處理，而不是處理完成，但你的服務提供者可能要求不同的成功回應。請遵循其 Webhook 合約。

在儲存任何資料前返回成功，如果程序崩潰，可能會遺失更新。等待所有下游操作完成則可能導致逾時及再次傳送。持久收件匣或佇列可在接收與處理之間提供分界。

使處理具備冪等性

冪等性是指再次處理同一事件時，不會重複產生其業務效果。發送方可能在你的伺服器已接受事件但確認訊息遺失後重試。因此，重複傳送應成為常規測試案例。

• 如有可用的事件識別碼，請使用文件所述的事件識別碼作為去重鍵，並限定於正確的服務提供者或帳戶範圍。
• 如果沒有識別碼，請根據穩定的事件欄位設計複合鍵，並測試其碰撞風險。
• 在儲存中以原子方式強制執行唯一性；獨立的「檢查，再插入」順序在並行傳送時可能出現競爭。
• 同樣要保護下游操作。重複事件不得再次發送送貨通知或重複執行財務操作。
• 根據服務提供者的重播行為及你的恢復要求設定保留期限，不要立即刪除去重記錄。

不要假設事件按時間順序到達

不要僅因請求最後到達，就覆寫目前的貨件狀態。請比較事件含義、時間戳及任何有文件記載的順序資訊。將較晚到達的檢查點保留在歷史記錄中，不要自動將顯示狀態調回較早狀態。同時，也要允許有文件記載的更正：規定已送達貨件永遠不能變更的僵化規則，可能會掩蓋合法例外或已更正的資訊。

實用設定清單

1. 確認服務提供者合約

在實作前，確認登記要求、支援的事件、負載結構、驗證、回應要求、逾時、重試行為及 API 限制。了解通知代表快照還是增量變更、一次傳送是否可以包含多筆記錄，以及訂閱時是否會發送初始狀態。

如要整合 17TRACK，請先參閱官方 Tracking API page 及 API documentation。使用服務提供者專屬文件確定請求欄位及回呼要求；上述通用負載不能取代該文件。確認你計劃部署的整合所需的存取條件及運作限制。

2. 保護接收端點

使用 HTTPS 及服務提供者文件所述的驗證機制。如果使用 HMAC 簽名，請準確驗證其指定的簽名輸入。若簽名基於原始請求位元組，驗證前先解析並重新序列化 JSON 可能會改變這些位元組，令簽名失效。對由密鑰衍生的簽名值使用常數時間比較。

如果有簽名時間戳或傳送識別碼，請套用文件記載的重播控制。有效簽名可以驗證訊息，但本身不能證明訊息是最新的。不要將密鑰放在 URL 及應用程式日誌中，支援密鑰輪換，並限制請求大小。在存在並持續維護 IP 位址範圍的情況下，IP 允許清單可以作為額外控制，但不能取代訊息驗證。

3. 將接收與業務處理分開

儲存足夠資訊，以追蹤及安全地重播已接受的事件。佇列工作程序應標準化更新、套用狀態轉換規則，並記錄操作結果。將反覆失敗的工作放入可供檢視的死信流程，而不是無限重試。由於追蹤負載可能包含與客戶相關的資料，請限制存取權及保留期限。

4. 在上線前測試故障路徑

• 傳送同一事件兩次，包括並行傳送。
• 在較新的檢查點之後傳送較舊的檢查點。
• 模擬佇列故障，以及接收後工作程序崩潰。
• 測試無效驗證、格式錯誤的 JSON 及過大的請求。
• 測試未知貨件、缺少可選欄位及新增欄位。
• 確認一個已送達包裹不會完成拆單訂單。
• 在恢復後重播事件，並確認通知仍然完成去重。

在安全的情況下容許新增欄位，但不要默默重新解讀未知狀態值。保留原始值，並透過已定義的後備或檢視流程處理未識別情況。

輪詢仍然適用的情況

輪詢適用於初始同步、故障後恢復，以及檢查未收到預期更新的貨件。然而，單純沒有訊息並不能證明 Webhook 發生故障：包裹可能確實沒有新的掃描記錄。應根據 API 的目前狀態或歷史記錄進行核對，而不是假設每件沒有動靜的貨件都需要發出警報。

在規劃規模時，簡化的輪詢模型為 requests per hour ≈ active shipments × polls per shipment per hour，前提是每次請求包含一件貨件。批次端點會改變這項計算。舉例來說，每小時檢查 1,000 件貨件四次，在重試前每小時會產生 4,000 個請求；這只是算術，不代表服務提供者配額或價格估算。

根據貨件活動及業務風險安排檢查，遵守速率限制，並加入抖動，避免所有工作同時開始。對於可重試的故障，使用有上限的退避機制，並遵循適用的伺服器指引。不要在未修正永久性憑證或驗證錯誤的情況下反覆重試。

實用的混合系統會使用 Webhook 處理日常更新，並針對疑似缺口進行 API 讀取。分開監控接收失敗、佇列存留時間、處理失敗、重複率及核對不一致。當時間戳可靠時，區分來源資料延遲、Webhook 傳送延遲及內部處理延遲。

常見問題

追蹤 Webhook 是即時的嗎？

它們可以減少等待下一個輪詢週期所造成的延遲，但不能保證承運商即時掃描或來源立即更新。端到端的新鮮度包括承運商報告、服務提供者處理、請求傳送及你自己的應用程式。

啟用 Webhook 後，我可以完全停止輪詢嗎？

如果服務提供者的恢復功能及你的業務要求認為這樣可以接受，則有可能。對於營運上重要的貨件記錄，請保留核對方法。這可以是針對性的，而不是持續輪詢每一件貨件。

如果我的 Webhook 端點離線，會發生甚麼？

恢復方式取決於發送方文件記載的重試政策。不要假設重試會無限期持續。恢復端點後，檢查失敗的傳送、使用受支援的重新傳送工具，並在可用時透過 API 核對受影響的貨件。

每個 Webhook 都應觸發客戶通知嗎？

不應該。事件可能是重複事件、歷史檢查點，或不會改變面向客戶狀態的更新。請根據完成去重的業務狀態轉換觸發通知，並為例外及更正設定規則。

成功的 HTTP 回應是否代表貨件更新已完成？

不一定。在非同步設計中，這表示接收器已根據約定的合約接受事件。請分開追蹤處理完成情況及下游通知結果，避免已接受的請求掩蓋工作流程失敗。

來源

• RFC 9110: HTTP Semantics — HTTP 回應語義，包括接受處理及 Retry-After。
• RFC 2104: HMAC—Keyed-Hashing for Message Authentication — 簽名驗證指引中引用的 HMAC 結構。
• GitHub Docs: Best practices for using webhooks — 關於 HTTPS、密鑰、非同步處理及傳送識別的一般工程指引；其服務專屬規則不代表貨件服務提供者的行為。
• 17TRACK Tracking API — 評估 17TRACK 追蹤整合的官方入口。
• 17TRACK API documentation — 實作要求的服務提供者專屬參考資料。