1.e签宝回调通知概述
企业开发者通过 Web服务来接收e签宝服务端推送的消息。
例如:签署人签署完成推送事件、签署流程结束推送事件等。
2.接收e签宝回调通知流程
3.接收回调通知如何实现?
3.1 准备一个支持 HttpPost的 Web服务
e签宝服务端将以 POST 方式推送 JSON 数据格式的消息,因此企业开发者的Web服务需要能够支持 HttpPost和 JSON 数据解析。
3.2 设置接收回调通知的地址
企业开发者可以通过 一步发起签署 或 签署流程创建 接口中的 noticeDeveloperUrl 参数来设置回调接收地址。
注:
- 接收回调通知的地址URL格式为 {scheme}://{host}:{port}/{path};
- 请保证接收回调通知的地址URL拼接正确,且互联网可成功访问。
3.3 接收并响应
3.3.1 接收e签宝回调通知
当某个事件发生后,e签宝会主动根据贵司传入的回调接收地址(noticeDeveloperUrl )发送POST请求,推送对应的事件通知信息。
例如:当签署人完成签署操作后,e签宝推送该签署人签署完成事件信息。
注:
- 请按照 e签宝回调通知服务器信息 配置贵司防火墙,以便成功接收e签宝回调通知。
请求头数据格式如下:
Content-Type:application/json; charset=UTF-8 X-Tsign-Open-App-Id:7111XXX X-Tsign-Open-TIMESTAMP:1563968035000 X-Tsign-Open-SIGNATURE-ALGORITHM:hmac-sha256 X-Tsign-Open-SIGNATURE:ZdTWCiDGlbJbDcOQbPEc0/BXKi+oGgNak97uc+7jbw8=
请求Body数据格式如下:
{"action":"SIGN_FLOW_UPDATE","flowId":"11111113a466442abbce094c9368ac7c","accountId":"22XXXe2a","authorizedAccountId":"33XXXe3a","signTime":"2019-07-24 19:33:06","order":1,"signResult":2,"thirdOrderNo":"cust0001","resultDescription":"签署完成","timestamp":1563967986960,"thirdPartyUserId":"A34006"}
其中:
action 为业务事件类型,企业开发者可以通过判断返回body中的 action 业务事件类型,从而进行下一步业务处理。 可通过查看 Action事件列表 了解电子签名SaaS API(标准版)中所涉及的业务类型。
Action事件类型可能会出现新增,建议开发者考虑兼容性处理,防止出现代码异常造成业务卡死。
例如,Action业务事件类型判断时,仅将贵司业务需要的类型进行判断并进入下一步业务,其他不需要的类型做忽略处理,这样可以防止新增类型对现有业务造成影响。
3.3.2 响应e签宝回调通知
当收到e签宝的回调通知后,开发者返回介于200~299的HTTP状态码给e签宝,e签宝均认为推送成功。
建议返回给e签宝的响应Body数据格式如下:
{"code":"200","msg":"success"}
【注意事项】
1. 开发者返回给e签宝的 HTTP状态码介于200~299之间,e签宝认为通知成功,否则e签宝认为通知失败。
2. 通知失败后,e签宝通知服务将会进行16次重试通知。重试机制如下:

(若中间重试通知成功,则中断不再继续重试)。
3. 为避免因e签宝通知服务解析 JSON 数据失败而导致重复通知,请确保返回的 JSON 数据中不含空格 \/等特殊字符,建议接收成功时直接返回{"code":"200","msg":"success"}
。
4. 为了保障回调通知的时效性和可靠性,建议开发者在接收到回调通知后在5秒内返回 HTTP 状态码(200)给e签宝通知服务。
5. 若开发者无法在5秒内完成回调通知相关业务处理,请采用异步方式进行后续业务处理。
4.Action事件列表
跟e签宝对接的平台方,可以通过回调通知返回的 Action 判断业务操作,从而进行下一步业务处理。
注:Action事件类型可能会出现新增,建议开发者考虑兼容性处理,防止出现代码异常造成业务卡死。
例如,Action业务事件类型判断时,仅将贵司业务需要的类型进行判断并进入下一步业务,其他不需要的类型做忽略处理,这样可以防止新增类型对现有业务造成影响。
Action事件类型 | Action事件名称(点击查看具体描述) |
SIGN_FLOW_UPDATE | |
SIGN_FLOW_FINISH | |
SIGN_DOC_EXPIRE_REMIND | |
SIGN_DOC_EXPIRE | |
BATCH _ ADD _ WATERMARK _ REMIND | |
FEEDBACK_SIGNERINFO | |
WILL_FINISH | |
PARTICIPANT_MARKREAD |
5.接收回调通知的地址URL格式说明
格式:{scheme}://{host}:{port}/{path}
注意:url中不能包含空格或特殊字符
说明:
scheme 指 https 或 http
host 指 贵司域名 或 贵司公网IP
port 指 服务对应的端口
path 指 贵司Web服务具体路径
正确的示例: | |
正确的URL格式 | |
正确的URL格式 | |
错误的示例: | |
只有地址,没有具体服务路径 | |
只有路径没有地址 | |
本地内网IP,互联网无法访问 | |
本地内网IP,互联网无法访问 | |
本地内网IP,互联网无法访问 | |
非URL格式 | test、123456 |
6.e签宝回调通知服务器信息
如果贵司需要防火墙配置后才允许e签宝消息通知服务推送数据,请根据下方信息进行贵司防火墙设置。
环境 | 公网IP |
沙箱模拟环境 | 47.96.79.204 |
正式环境 | 118.31.35.8 |