什麼是回調通知

回調通知是一種系統主動發送事件資訊的機制。

與機構主動調用 API 查詢資料不同，回調通知會在事件發生後，由 Finger Manager 主動向機構伺服器發送資料。

典型流程為：Finger Manager 發生業務事件 → 系統觸發回調 → 向機構 Callback URL 發送事件資料 → 機構伺服器接收 → 執行後續業務邏輯。

這種方式可以減少機構持續輪詢 API 的需求，並提高系統之間的資料同步效率。

支援的使用場景

回調通知可用於用戶註冊完成、KYC / KYB 狀態變化、訂單建立、訂單狀態變化、成交通知、持倉變化、入金狀態變化、出金狀態變化、帳戶狀態變化、風險事件、系統通知、訂閱狀態變化及自訂業務事件等場景。

實際可使用的回調事件，以機構目前啟用的 Finger Manager 模組及系統配置為準。

Callback URL

機構可以在 Finger Manager 中配置用於接收回調資料的伺服器地址。

例如：https://api.example.com/finger/callback。

當指定事件發生後，Finger Manager 將向該地址發送對應事件資料。

建議機構使用 HTTPS 地址，以確保資料傳輸過程的安全性。

回調資料

回調內容通常會包含 Event Type、Event ID、Organization ID、User ID、業務對象 ID、事件發生時間、目前狀態、相關業務資料、請求簽名及其他擴展欄位。

不同事件類型所包含的資料欄位可能不同。

機構可根據 Event Type 判斷事件類型，並執行對應的業務邏輯。

安全驗證

為了防止未經授權的請求，機構可以對回調請求進行安全驗證。

根據實際接入方式，可使用 API Secret、Signature、Timestamp、Token、IP 白名單和 HTTPS。

機構在收到回調後，應驗證請求來源及簽名資訊，再進行後續業務處理。

回調失敗與重試

如果機構伺服器暫時無法正常接收回調，例如伺服器不可訪問、請求超時、返回錯誤狀態碼或發生網路異常，系統可根據對應的回調機制進行重新發送或記錄失敗狀態。

機構也應確保 Callback URL 長期保持可訪問狀態，並正確返回 HTTP 狀態碼。

與 API 的區別

API 與回調通知解決的是不同的資料交互場景。

API 表示機構主動請求 Finger Manager 獲取或提交資料。

回調通知表示 Finger Manager 在事件發生後主動向機構系統發送資料。

在實際系統集成中，通常會同時使用 API 與回調通知。例如 API 用於查詢訂單詳細資訊，回調通知用於實時告知機構訂單狀態已經發生變化。

使用示例

例如，當用戶在 Finger Trader 中提交一筆訂單後：用戶提交訂單 → Finger Manager 接收訂單 → 系統生成訂單事件 → 向機構伺服器發送回調 → 機構系統接收訂單資訊 → 執行風控、訂單處理或其他業務邏輯。

又例如，當用戶的 KYC 審核狀態發生變化：KYC 狀態更新 → Finger Manager 觸發回調 → 機構系統收到狀態變化 → 自動更新客戶資料或帳戶權限。

說明

回調通知主要用於 Finger Manager 與機構自有系統之間的實時系統集成。

機構可以根據自身業務架構決定接收哪些事件、回調發送到哪個伺服器、收到事件後執行什麼業務邏輯，以及是否繼續轉發至其他內部或第三方系統。

透過回調通知，可以讓 Finger Manager 更容易融入機構現有的技術基礎設施，而無需改變機構原有的核心系統架構。