什么是回调通知

回调通知是一种系统主动发送事件信息的机制。

与机构主动调用 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 更容易融入机构现有的技术基础设施，而无需改变机构原有的核心系统架构。