設定 Webhook
- 輸入接收端地址：在 DGrid 的 Webhook 設定中輸入並儲存您或技術團隊提供的公開 HTTPS URL。
- 啟用 Webhook。
- 取得 Signing Secret：點擊 Rotate Secret，安全複製產生的密鑰並加入接收端設定。每次輪替都會產生新密鑰；請更新接收端，並在排隊投遞完成前保留舊金鑰。
- 選擇事件：啟用需要接收的通知類型。
- 測試通知：確認接收端可接受通知並驗證簽章。
可用事件
以下 6 類事件皆可在 Webhook 設定中選擇。請以通知 JSON 最外層的eventType 辨識事件，保留識別碼的大小寫、句點與底線。
儲值餘額與訂閱餘額是分開的。每個訂閱在每個 UTC 月份最多發送一次訂閱餘額不足通知，沒有獨立的訂閱餘額耗盡事件。自動儲值失敗指實際嘗試失敗，不包含尚未建立嘗試前的資金或授權警告。
傳入請求
DGrid 向已儲存的 URL 發送 HTTPPOST，並使用 Content-Type: application/json。所有通知使用相同的外層結構：
事件資料
以下範例僅替換共同結構的data。識別碼、時間與餘額均為範例值。
儲值餘額不足：balance.low
儲值餘額耗盡：balance.depleted
eventType 為字串，test 為布林值。balance 是以 USD 計的帶正負號十進位字串，可為零或負數，僅代表儲值餘額，不含訂閱額度。請保留精度，不要轉成浮點數，也不要套用電子郵件顯示的四捨五入或截斷規則。
自動儲值完成：auto_recharge.succeeded
自動儲值失敗：auto_recharge.failed
attemptId 識別自動儲值嘗試；state 分別固定為 confirmed 或 failed；occurredAt 是 UTC RFC 3339 事件時間，可能包含小數秒。資料僅包含這三個欄位，沒有內層 eventType 或 test，也沒有金額、交易雜湊、錢包或失敗原因。
訂閱啟用：subscription.activated
sourceId 是訂閱 UUID。
訂閱餘額不足：subscription.balance_low
sourceId 結合訂閱 UUID 與 UTC 月份，格式為 <subscription UUID>:YYYY-MM。訂閱事件的三個欄位皆為字串，occurredAt 為 UTC RFC 3339 時間戳記。資料不含方案名稱、訂閱日期、額度、百分比或錢包；請勿假設具有電子郵件顯示的所有細節。
測試通知
測試通知最外層的test 為 true。每種事件的測試 data 都使用相同的三欄位結構；data.eventType 與選取事件及外層 eventType 相同。例如選擇自動儲值完成時：
test。測試沒有正式事件的 attemptId 或 sourceId，空白 balance 也不代表零。請勿使用測試通知修改餘額、記錄儲值或啟用訂閱。
驗證簽章
請求包含四個相關標頭：
標頭名稱不區分大小寫，沒有獨立的簽章金鑰版本標頭。
Rotate Secret 顯示的 Signing Secret 是 32 位元組金鑰的無填補 base64url 編碼。計算 HMAC 前需解碼為位元組，不能直接以顯示的密鑰文字當作金鑰。
DGrid-Signature，並要求協定版本為 v1。建議採用 5 分鐘的時間戳記容許範圍以限制重播，並同步接收端時鐘。驗證後才解析 JSON，並確認 DGrid-Event-Id 與 id 相同。
回應投遞
將已驗證通知可靠地持久化後，在 5 秒內回傳任意 HTTP2xx。例如先寫入持久化佇列，再回傳：
200 的 JSON 本文表示錯誤，也會視為已接受。
非 2xx、網路失敗或逾時會觸發重試，包含首次在內最多共 5 次嘗試。DGrid 不會跟隨重新導向。耗時的業務處理請在通知已持久化後進行。
通知可能重複且順序不保證。請以重試時保持不變的外層 id 去重。已接受的重複通知仍回傳 2xx，但不要重複執行業務操作。重試時時間戳記、簽章與原始位元組可能變更，請勿使用它們或 createdAt 去重或判定業務事件順序。