Webhook 的登錄方法

要接收 Webhook，需在開發者入口對應用程式登錄「Webhook 端點」。端點是指 ReceiptRoller 在事件發生時發送 POST 的目標 URL。可對 1 個應用程式登錄多個端點，因此可依用途或環境分開運用。

前提

• 在開發者入口應用程式已登錄（新增建立應用程式）
• 已備妥接收用的伺服器與 HTTPS URL
• 接收端能安全保管簽章驗證用的密鑰

登錄步驟

步驟 1：開啟應用程式的「Webhook」分頁

開發者入口 → 應用程式一覽 → 開啟目標應用程式 → 點擊上部分頁的「Webhook」。

步驟 2：點擊「追加端點」

按下右上的「＋ 追加端點」按鈕，登錄表單會開啟。

步驟 3：輸入必要項目

步驟 4：點擊「建立」

登錄完成後，會轉移到端點的詳細畫面。這裡 簽章驗證用密鑰（Webhook Secret） 僅初次顯示。請務必在此時保管到安全的場所。

訂閱事件的選法

強烈建議訂閱的事件縮減至必要的即可。理由如下。

• 接收端伺服器的負荷會下降
• 處理邏輯會變簡單（不需要事件的分歧消失）
• 監視時的噪音會減少

例如「庫存同步」為目的的話僅訂閱 inventory.changed 與 inventory.low_stock，receipt.* 或 campaign.* 不訂閱。有多個用途的情況，依用途分開端點在運用上較乾淨。

測試投放

為確認登錄的端點能正確接收，可從開發者入口發送測試事件。

1. 點擊端點詳細畫面的「測試投放」按鈕
2. 選擇想發送的事件種類
3. 按下「發送」則會投放範例酬載
4. 確認接收端的日誌與回應

測試投放的酬載中含有 "test": true 旗標。接收端不想流到正式處理的情況，請實作為看此旗標而忽略。

多端點的分開運用

1 個應用程式最多可登錄 20 件端點。常見分法的例子：

編輯、無效化、刪除

• 編輯：URL、訂閱事件、對象店鋪、說明可隨時變更。從下次投放起反映
• 無效化：以「有效/無效」開關可暫停。停止中期間發生的事件不會被投放（也不會被保留）
• 刪除：完全刪除則無法還原。將端點本身保留而無效化的做法較安全

登錄後的確認檢查清單

• ☐ 接收 URL 以 https:// 可從外部存取
• ☐ 已安全保管 Webhook Secret
• ☐ 已實作簽章驗證邏輯
• ☐ 以測試投放確認 2xx 有回傳
• ☐ 已實作 event_id 基底的冪等性檢查
• ☐ 為 10 秒以內回傳回應的構成

相關指南

• Webhook 的概要
• 簽章驗證與安全性
• 重送、順序、冪等性的設計
• 監視與失敗時的對應
• 返回開發者幫助中心