异步回调通知接收说明

1.异步回调通知概述

• 首先，开发者配置回调通知Web Url地址。
• 每当，认证相关事件发生时（如用户完成实名），e签宝通知服务将会创建一个JSON对象，其中包含事件类型和与该事件相关的数据等信息。
• 然后，e签宝通知服务通过 HTTP POST 请求将JSON对象发送到开发者配置的回调通知 Web Url中。
• 开发者业务系统在收到回调通知后，可根据事件类型和相关数据做下一步的业务处理。

其流程描述如下：

2.接收认证类回调通知

2.1 准备一个支持 HTTP POST 的 Web 服务

e签宝通知服务将以 HTTP POST 方式推送 JSON 格式的数据，因此开发者所提供的 Web 服务需要能够接收并解析来自HTTP POST 请求的 JSON 数据并能够返回相应 HTTP 状态码。

2.2 设置回调通知Url地址

如果以下两种设置回调通知方式均设置，均会触发回调通知（地址相同就触发两次）

方式一：接口设置

开发者可通过每个认证服务内的接口中的notifyUrl参数来配置回调通知Url地址（接口配置的不返回事件类型：action）。

方式二：开放平台订阅

开发者登录e签宝 开放平台 后点击【控制台】进入e签宝开发者控制台，在页面上方先选择【正式服务】（沙箱环境则选择【沙箱服务】，其他流程一致），然后在页面下方左侧点击【应用管理】-【我的应用】后在右侧应用列表页面中点击【配置】进入“应用配置”页面，选择【消息推送】模块的“添加”按钮即可配置接收回调通知的URL，并需要在事件订阅中勾选对应事件。如下图：

2.3 接收并响应

2.3.1 接收e签宝回调通知

当某个事件发生后，e签宝会主动 POST 请求开发者所设置的回调通知 Url 地址，并推送对应的事件数据信息。

例如：当用户完成认证操作后，e签宝将推送该认证完成事件数据信息。

请求头数据格式如下：

{
  "X-Tsign-Open-TIMESTAMP":"1713508339505",
  "X-Tsign-Open-SIGNATURE-ALGORITHM":"hmac-sha256",
  "X-Tsign-Open-App-Id":"74XXXXXX",
  "X-Tsign-Open-SIGNATURE""60c6719d332420f251234d72631e93e83e80061f47f78bc483a851a710"
}

请求Body数据格式如下：

{
    "flowId": "34610511111183554",
    "success": true,
    "contextId": "1234455",
    "verifycode": "19e5aa11111111889cc56dfeb1b6b21",
    "serviceId": "346111111113783554",
    "status": true
}

其中：

action 为业务事件类型，开发者可以通过判断返回 JSON 中的 action 业务事件类型，来进行下一步业务处理。

可通过查看文末附1 Action事件列表了解认证类相关事件的回调通知数据。（只有通过开放平台订阅方式配置的才有action）

2.3.2 响应e签宝回调通知

e签宝的回调通知触发后，返回的200 ~ 299之间的 HTTP 状态码均会被e签宝通知服务认定为通知成功。

除返回 HTTP 状态码之外，同时建议开发者按以下 JSON 格式向e签宝通知服务返回 Body体数据（e签宝不对开发者返回的Body体数据做判断）。

{"code":"200","msg":"success"}

3.e签宝回调通知安全机制

为了保证回调通知数据推送的安全，e签宝提供IP白名单模式和签名验签模式两种模式供开发者选择。

两种模式可以单独使用，也可以组合使用。具体详见 异步回调通知安全机制。

附1 Action事件列表

开发者可通过判断e签宝通知服务推送的 JSON 中的 Action 事件类型，从而进行下一步业务处理。

附2 回调通知URL格式说明

URL格式：{scheme}://{host}:{port}/{path}