Webhook開發人員指南
簡介
FedEx的查詢Webhook會在貨件的整個生命週期內,提供近乎實時的貨件更新。
有別於必需應用程式來要求貨件狀態的查詢API,當有新資訊可用時,Webhook會自動傳送貨件更新。
本指南涵蓋:
- 三項整合原則
- Webhook的運作方式
- 處理Webhook數據
- 顧客通知
- 時間戳記
- 最佳做法及常見整合問題
三項整合原則
要確保Webhook成功整合,必須遵循三項原則。
將每筆Webhook數據作為貨件狀態更新來處理
請勿假設每筆數據均代表新的查詢里程碑。每當有新的貨件資訊可用時,FedEx會發佈新的數據。
數據可能包含:
- 新的查詢事件
- 最新的遞送預測
- 送達證明資訊
- 收件人資料
- 其他貨件資料更改
多筆數據可共用同一個查詢里程碑,但各筆數據可能包含不同的貨件資料。
儲存並合併貨件資料
每筆數據可能包含新或最新的貨件資料。請儲存每筆Webhook數據,並將新資訊合併至現有貨件記錄。
請勿使用最新數據覆寫現有的貨件記錄。取而代之,請保留先前收到的貨件資料,並納入新資訊,以在貨件的整個生命週期內保持貨件記錄為完整及最新。
根據業務規則來決定後續操作
根據業務規則來決定何時更新系統或通知顧客。
請勿僅根據事件代碼觸發操作。在更新顧客專用的應用程式或傳送通知前,請先評估:
- 查詢里程碑
- 貨件可用性
- 通知時機
- 業務要求
建議處理模型
以下圖表說明了在一般實施情況下,這三項Webhook整合原則如何互相配合。每筆Webhook數據均會作為貨件狀態更新來處理,合併至中央化貨件記錄,並根據業務規則作評估,然後才會更新應用程式或向顧客傳送通知。
Webhook的運作方式
每當有貨件資訊出現變化或可用時,FedEx會發佈新的Webhook數據。貨件在整個生命週期內可生成多筆數據,包括與同一項查詢里程碑相關聯的多筆數據。
額外數據可能包括:
- 查詢里程碑:已收件、運送中、已在送件和已送達。
- 貨件資料:送達證明 (PPOD)、簽收證明 (SPOD)、GPS送達證明 (GPS POD) 及收件人資訊。
- 遞送預測更新:預計送達日期及時間更改。
- 未能送達事故:貨件及未能送達事故更新及原因。
- 貨件中繼資料更新:地址更新、參考資料及服務詳情。
- 營運修正:其他查詢里程碑及
previousEvents更新。
請注意:已送達貨件未必會提供相片證明。相片證明是否可用,需視乎遞送類型、簽收要求及其他業務規則而定。
每筆數據代表貨件的已知最新狀態。請處理每筆數據,確保您的貨件記錄為完整及最新。
理解Webhook更新
下列例子展示了在同一件貨件的整個生命週期內,系統如何為其生成多筆Webhook數據。部分數據會引入新的查詢里程碑。其他數據則會新增貨件資訊,例如遞送預測、送達證明數據或貨件詳情。
重要事項:系統可能會為同一項查詢里程碑生成多筆Webhook數據。請處理每筆數據,確保系統會將新的貨件資訊納入貨件記錄。
處理Webhook數據
請將每筆Webhook數據作為貨件狀態更新來處理。
請勿假設每筆Webhook數據均代表新的查詢里程碑。每當有新的貨件資訊可用時,FedEx會傳送新的數據。以已送達的貨件為例,當系統新增或更新送達證明資訊、收件人資訊或其他貨件資訊時,可能會生成額外數據。
針對每筆數據,請思考以下問題:
- 哪個查詢里程碑出現變化?
- 哪些貨件資訊出現變化?
- 此項更新會影響顧客專用的應用程式嗎?
- 此項更新會觸發通知嗎?
處理貨件記錄
同時監察scanEvent和previousEvents。
scanEvent包含與數據相關聯的目前查詢里程碑。previousEvents包含其他貨件記錄,包括可能不會顯示為目前scanEvent的里程碑。
部分查詢里程碑會在previousEvents中顯示,而非發佈為新的scanEvent。如應用程式僅處理scanEvent,便可能會遺漏貨件更新,並生成不完整的貨件記錄。請處理兩個系列的數據,全面掌握貨件狀況。
維護貨件記錄
請儲存每筆Webhook數據,並將新資訊合併至現有貨件記錄。
完整的貨件記錄可涵蓋以下各項,提供近乎實時的貨件查詢功能:
- 貨件查詢儀表板
- 顧客服務應用程式
- 訂單管理系統 (OMS)
請以每筆數據來更新貨件記錄,確保盡量保持貨件狀況準確完整。
顧客通知
請根據您的業務需要,以及您希望提供之貨件資訊的詳盡程度,選擇一項通知策略。
FedEx查詢Webhook會以近乎實時的方式,傳送查詢里程碑及貨件資料變化的更新。請運用業務規則來判斷哪些更新與業務相關,以及哪些更新可以忽略。
常見的通知策略包括:
近乎實時的通知
當發生查詢里程碑後,立即傳送通知。
優勢
- 最快捷的顧客通訊
- 最少延遲
注意事項:額外貨件資料可能尚未提供。
豐富詳盡的通知
當達到某個查詢里程碑後,請等候數分鐘,待額外貨件資訊傳入。
例如當某筆里程碑傳入後,請等候數分鐘以收集:
- 送達證明 (POD)
- 簽收證明 (SPOD)
- GPS送達證明
- 收件人資料
優勢
- 為顧客提供更完整的貨件更新
- 減少後續通知
- 減少顧客聯絡顧客服務部的次數
FedEx建議於里程碑傳入後等待約五分鐘,因為系統通常會在首項遞送事件後的短時間內,新增送達證明資訊。
通知時機建議
通知時機因應顧客和使用個案而異。不過,下列建議一般適用於購買後向收件人傳送的通知。如為其他通知類型(例如向企業用戶、顧客服務部代表等不同對象傳送的通知),請選擇適合相關使用個案的通知策略。
- 預計送達:在承諾日期和首個預計送達日期均可供查閱後,等待約15分鐘。
- 已在送件:立即傳送,或者根據您的業務時間表傳送(例如每日早上8:00)。
- 已送達:等候約5分鐘,待遞送附加資訊傳入。
- 嘗試遞送:採用與已送達事件相同的做法,待遞送資訊傳入。
按照業務資料建立通知規則
並非每項貨件更新都需要通知。制定切合您業務需要的通知規則。
建議做法
請勿僅根據eventCode觸發通知。
評估:
- 查詢里程碑
- 所需的貨件資料
- 業務規則
僅當所需資料可供查閱時,才生成通知。
此做法有助防止:
- 重複通知
- 缺漏遞送資訊
- 遞送通知不完整
- 不必要的後續通知
時間戳記
請根據您的使用個案,採用合適的時間戳記。
eventCreateTime:貨件事件的發生時間。用於向顧客顯示的查詢記錄。- 訊息傳送時間:FedEx傳送Webhook數據的時間。僅用於偵錯及監察,不應用於顧客專用的體驗。
eventCreateTime反映貨件事件的發生時間。FedEx在日後新增額外貨件資訊時,不會更新此值。例如,即使後續數據新增送達證明資訊或其他貨件更新,已傳入的事件仍會保留其原有的eventCreateTime。因此,應使用eventCreateTime來識別事件的發生時間,而非使用新增相關貨件資訊的時間。
在部分情況下,事件時間可能無法提供。在此情況下,時間戳記可能會包含預設值00:00:00。當有更準確的時間戳記可用時,額外數據可能會包含該時間戳記。
最佳做法及常見整合問題
最佳做法
- 處理每筆Webhook數據 — 每則訊息都可能包含新的查詢事件或貨件資料更新。
- 將增量更新合併至您現有的貨件記錄。
- 同時監察
scanEvent和previousEvents,全面掌握貨件記錄。 - 根據業務規則來觸發客戶通知,而非僅依據原始事件。
- 在通知顧客前,先等待預期的附加資訊(例如送達證明圖像、簽收證明、GPS等)傳入。
- 設計具備冪等性的彈性處理機制,管理重複及亂序訊息。
常見整合問題
- 假設每筆數據均代表新的查詢里程碑。
- 使用最新數據覆寫貨件記錄。
- 僅依賴
scanEvent。 - 僅根據
eventCode觸發通知。 - 假設首筆傳入數據包含所有遞送詳情。
- 假設Webhook訊息僅會傳入一次,或者會按時間順序傳入。
摘要
請將每筆Webhook數據作為貨件狀態更新來處理。儲存並合併貨件更新,同時監察scanEvent和previousEvents,並根據業務規則決定何時更新應用程式或通知顧客。
此做法有助確保貨件狀況資訊準確、查詢記錄完整,並讓顧客掌握更全面的資訊。
