追蹤 Webhook 端點應返回甚麼?狀態碼、逾時與重試?
追蹤 webhook 端點在接受事件進行處理後,應快速並明確地返回 2xx 回應。在大多數整合中,最安全的做法是驗證請求、驗證負載、儲存或將事件加入佇列,然後以 200 OK 或 202 Accepted 確認收到。對於發送方不應重試的請求,使用 4xx 回應;當暫時性的伺服器端問題導致無法接受請求時,使用 5xx 回應。確切的逾時及重試行為仍取決於 webhook 供應商的合約,因此你的實作應以已記錄的發送方行為為基礎,而不是依賴假設。
對於追蹤或貨件狀態 webhook,這項區別十分重要,因為配送事件可能會多次到達、以亂序到達,或在網絡故障後被重新傳送。端點的工作不一定是在回應前完成每項業務操作。它首先要做的是可靠地判斷事件是否已被接受。
實際上的回應合約
Webhook 回應有兩個對象:發送系統和你自己的應用程式。發送方需要清晰的 HTTP 結果,以決定是否將配送標記為成功、重試,或停止。你的應用程式則需要足夠時間驗證並持久記錄事件。當端點具備簡短的同步路徑,以及獨立的非同步處理路徑時,這些目標會更容易實現。
- 透過 HTTPS 接收 HTTP 請求。
- 檢查供應商要求的簽名、驗證憑證、時間戳記或其他請求完整性控制措施。
- 解析並驗證負載,但不要執行緩慢的下游工作。
- 將事件,或去重記錄及事件參照,寫入持久儲存或可靠的佇列。
- 返回明確的 2xx 回應。
- 以非同步方式處理追蹤更新、客戶通知、庫存變更或其他業務操作。
如果事件只存在於處理程序記憶體中,回應不應聲稱已接受該事件。如果應用程式在返回成功後立即崩潰,尚未持久化的事件可能會遺失,而發送方卻會認為配送已成功。因此,你返回 2xx 的時間點應與實際的持久性保證相符。
Webhook 應返回哪個狀態碼?
| 回應 | 對發送方的含義 | Webhook 的常見用途 |
|---|---|---|
200 OK | 請求已被接受並成功處理。 | 驗證及持久接受後的實用預設選擇。 |
202 Accepted | 請求已被接受以進行處理,但工作可能仍會繼續。 | 事件已安全加入佇列,但業務處理以非同步方式進行時十分有用。 |
204 No Content | 請求成功,且不需要回應本文。 | 供應商接受空白成功回應時適用。 |
400–499 | 請求無效、未經授權,或按目前方式傳送時不被接受。 | 負載格式錯誤、驗證失敗、簽名無效,或被永久拒絕的事件。 |
429 Too Many Requests | 接收方正在實施速率限制。 | 僅在發送方的重試行為與你的速率限制政策相容時使用。 |
500–599 | 由於伺服器端或暫時性問題,接收方無法接受請求。 | 資料庫故障、佇列故障、依賴服務故障或未預期的應用程式錯誤。 |
200 OK 通常是最不令人意外的選擇,因為它普遍被理解為成功接收。當端點已接受事件以便稍後處理時,202 Accepted 在語義上也很有用。兩者都不是自動正確的選擇:發送方文件可能會定義哪些 2xx 回應會被視為成功,而部分供應商可能要求特定的本文或內容類型。
不要僅因 HTTP 請求已抵達你的伺服器,就返回 2xx 回應。如果簽名驗證失敗,或無法安全解讀負載,4xx 回應通常更符合實際。相反,如果只是暫時性的資料庫故障,而事件稍後可能成功,則不要返回 4xx。5xx 回應讓支援重試的發送方有機會再次配送事件,但供應商可能會採用自己的政策。
應如何處理逾時?
Webhook 逾時值因供應商而異。並不存在所有追蹤平台都使用的通用 HTTP 逾時,而發送方可能會在你的應用程式完成緩慢操作前停止等待。將發送方記錄的逾時視為最長界限,而不是目標。你的端點通常應在該界限之前很久就返回回應。
最常見的設計錯誤,是在確認 webhook 前完成所有下游工作。處理程序可能會依次呼叫資料庫、訂單管理系統、通知服務及分析管道。只要一個依賴服務速度緩慢,即使你的應用程式最終完成工作,發送方仍可能看到逾時。之後發送方可能重試,造成重複處理或相互競爭的更新。
將同步路徑限制在作出安全接受決定所需的工作。這通常包括請求驗證、基本結構描述驗證、持久事件儲存及發佈至佇列。將昂貴的資料補充、承運商查詢、客戶訊息及第三方 API 呼叫交由工作程序處理。將接收、驗證、持久化及確認事件所花的時間,與處理事件所花的時間分開監控。
逾時不等同於業務操作失敗。從發送方角度看,逾時通常表示它沒有收到可用的成功回應。你的服務可能在連線關閉前已成功儲存事件。這就是即使端點看似可靠,仍需要冪等性及去重的原因。
甚麼原因會導致重試?
Webhook 發送方可能在連線錯誤、逾時,或收到其合約分類為不成功的回應後重試。確切的時間表、最大嘗試次數、退避演算法及配送時限會因供應商而異。除非供應商文件明確列出,否則不要承諾固定的重試次數。
接收方應假設重試可能發生,並有意識地為此設計:
- 在可用時使用事件識別碼。 使用唯一限制或等效的去重鍵儲存該識別碼。
- 使處理具備冪等性。 對同一配送狀態更新套用兩次,不應發送兩則客戶訊息、建立兩次退款,或錯誤地推進訂單。
- 保留原始負載或有用的稽核記錄。 這有助於重播、調查及對賬。
- 分開接受與處理。 工作程序可以重試內部故障,而不必迫使發送方重複整個 HTTP 交換。
- 記錄回應碼及延遲。 5xx 回應、逾時或重複事件識別碼增加,可能在使用者報告遺失追蹤更新前揭示故障。
如果原始事件已被持久接受,重複事件通常應收到成功回應。對每個重複事件返回錯誤可能觸發不必要的重試。端點可以記錄該事件曾經出現、略過重複的業務操作,並返回與新接受事件相同的成功類別。
何時應返回 4xx、429 或 5xx?
當重試相同請求不太可能解決問題時,返回 4xx。 例子包括簽名無效、缺少必要驗證、負載形狀不受支援,或請求違反永久驗證規則。在選擇 4xx 前,請確認發送方是否將該狀態視為永久失敗。部分平台對失敗配送有自己的規則。
謹慎使用 429。 HTTP 將 429 定義為速率限制,而 Retry-After 標頭可以傳達何時適合重試。然而,並非所有 webhook 發送方都以相同方式解讀 429。如果你的佇列已滿或服務過載,請確認供應商會安全地重試,且其重試時間表不會令過載惡化。有限容量的接收佇列及背壓方案,通常比讓請求不可預測地失敗更好。
當接收方因暫時性問題而無法安全接受事件時,返回 5xx。 這包括資料庫不可用、持久佇列寫入失敗,或妨礙驗證或持久化的內部錯誤。返回 200 卻默默捨棄事件,會令復原更加困難,因為發送方沒有理由再次嘗試。
避免依賴 301、302 或 307 等重新導向來配送 webhook。不同客戶端對重新導向的處理方式各異,而重新導向已簽名的請求可能會令目的地、方法及本文變得含糊。請改為使用最終的 HTTPS 端點設定供應商。
追蹤事件的可靠回應政策
對大多數追蹤 webhook 整合而言,以下政策是合理的起點:
- 事件通過驗證並已持久儲存或放入可靠佇列後,返回
200或202。 - 對無效簽名、無效驗證或永久無法使用的負載,按照供應商記錄的規則返回 4xx 回應。
- 當暫時性故障阻止持久接受時,返回 5xx。
- 對已安全識別的重複事件返回成功回應,同時防止重複的業務影響。
- 保持處理程序快速,並測量其確認延遲。
- 在正式推出前測試逾時、重試、重複、亂序、格式錯誤及供應商故障情境。
如果你正在整合追蹤 API,請先查閱供應商的 webhook 文件,並確認可接受的成功碼、請求簽名方法、逾時、重試觸發條件、負載結構描述及事件識別碼。對於 17TRACK 整合,應以 官方 Tracking API 文件 核實供應商特定的合約,而不是從一般 HTTP 實務推斷。
實作檢查清單
- 端點可透過 HTTPS 存取,並具備穩定的正式環境 URL。
- 驗證及簽名驗證在業務處理前完成。
- 在簽名檢查及疑難排解需要時,保留原始請求或可驗證的表示形式。
- 在發送成功回應前持久化事件。
- 重複配送是安全的,不會重複執行不可逆操作。
- 工作程序可以獨立於發送方的 HTTP 重試週期,重試內部處理。
- 記錄包括事件 ID、配送時間、回應碼、處理狀態及關聯 ID,但不暴露機密。
- 警報會區分端點逾時、4xx 驗證失敗、5xx 故障、佇列延遲及重複配送。
- 已使用真實或沙盒事件測試供應商記錄的行為。
常見問題
對 webhook 而言,200 OK 是否比 202 Accepted 更好?
兩者都沒有普遍更好。當請求已被接受,而你的整合將該回應視為一般成功時,使用 200 OK。當事件已被接受以進行非同步處理時,使用 202 Accepted。請確認發送方將所選的 2xx 回應分類為成功。
Webhook 端點是否應等待追蹤更新完全處理?
通常不應。它只應等待事件完成驗證、確認並被持久接受。長時間運行的工作通常應在確認後進行,以免緩慢的依賴服務導致可避免的逾時及重試。
同一追蹤事件到達兩次時應怎樣處理?
使用供應商的事件 ID 或經仔細設計的等效鍵識別它,略過重複的副作用;如果事件已被接受,則返回成功回應。這樣可以在不掩蓋新處理故障的情況下,安全地進行重試。
無效簽名應返回 400 還是 401?
選擇取決於你的驗證模型及供應商記錄的預期。兩者都可以傳達拒絕,但一致性比普遍選擇其中一個更重要。不要確認收到你無法驗證真實性的事件。
5xx 回應是否一定會導致重試?
不會。許多 webhook 系統會重試逾時及伺服器錯誤,但重試觸發條件及時間表因供應商而異。將重試視為記錄在案的整合行為,並在測試環境中驗證。
來源
- RFC 9110: HTTP Semantics — 成功、客戶端錯誤、伺服器錯誤、重新導向及回應處理的定義。
- RFC 6585: Additional HTTP Status Codes —
429 Too Many Requests的規範。 - Stripe Webhooks Documentation — 有關 webhook 回應、非同步處理及重複事件處理的實務指引。
- GitHub Docs: Handling Webhook Deliveries — webhook 整合的配送檢查及運營考量。
- 17TRACK Tracking API Documentation — 實作追蹤 API 整合時查閱的供應商特定文件。


