僅註冊您需要的事件
使用POST /v3/webhooks 建立端點。僅訂閱您整合中所需的、有文件記載的事件。此範例使用 transfer.state_changed。
data.id 儲存為 WEBHOOK_ID。開啟由 GET /v3/webhooks/portal 回傳的入口網站,取得此端點的簽章密鑰,並將其與您的 API 金鑰分別存放在密鑰管理員中。
解析前先驗證
Swipelux 透過 Svix 派送新的 webhook 整合。請使用您的端點簽章密鑰以及以下標頭驗證原始請求主體:svix-idsvix-timestampsvix-signature
保存、確認,然後處理
在信封id 上設定唯一性約束。持久化已驗證的信封、儘快回傳 2xx,然後以非同步方式處理。
若事件 ID 已存在,請確認派送但不重複執行已完成的副作用。透過您自己的重試佇列繼續處理待辦或失敗的本地工作。切勿將信封的 attempt 欄位當作去重複的鍵或傳輸重試計數器。
重新讀取當前狀態
Webhook 的順序並非權威的資源歷史紀錄。請使用resource.type 與 resource.id 定位物件,然後在更新您的系統前,先取得其當前狀態。
對於轉帳事件,呼叫 GET /v3/transfers/{transferId}:
復原派送
使用GET /v3/webhooks/portal 開啟派送日誌、重試失敗派送或啟動手動重播。
每次重播皆須經過相同的簽章驗證與可靠收件匣。若欲於停機後復原,請重播受影響的時段,並重新讀取每個所引用的資源。已完成的事件 ID 會保持無操作;未完成的紀錄則會以非同步方式繼續。
接下來,請於沙箱中驗證重複與亂序派送,然後完成上線 清單。