回调通知能力V1

功能介绍

2023年5月15日之后注册的企业，将默认使用新回调通知，请参考回调通知V2

若客户主动选择回调通知V2，请与客户经理联系处理

通过回调通知，您可以在合同状态产生变化以及发生印章、模板、员工相关操作等场景接受到来自电子签的回调通知。

如您需要使用此功能，需提供能接受并处理 HTTP POST 请求的回调地址，请确保该地址提供的服务可公网访问并能正常处理回调通知。

电子签推送的回调内容有进行加密处理，在接受到回调通知后需用配置好的 Key 进行解密。

配置回调地址

登录 腾讯电子签控制台 在集成管理中，选择生产运行（如果当前为测试环境，请选择测试联调）。

在参数配置中设置回调地址，请确保填入的地址能够接受并处理 HTTP POST 请求，并返回状态码200表示处理正常。选择点击系统生成可以随机生成解密的Key。此处支持配置多个回调地址并同时生效。

支持的回调场景

• 合同发起以及签署相关回调
• 印章相关回调
• 模板相关回调
• 企业与员工相关回调

!各类型回调的数据结构并不完全相同，请进行区分处理。

回调解密步骤

1. 对收到的数据进行 Base64 解码得到密文。
2. 对密文进行对称解密，算法为 AES-256-CBC，密钥为腾讯电子签提供的 CallbackUrlKey，IV 取 CallbackUrlKey 值的前16位，数据采用 PKCS#7 填充。
3. 解密得到的数据为输入参数的 Json 格式。

   解密代码可以参考 解密代码Demo

回调 FAQ

回调地址是否支持同时配置多个？

支持，回调地址可以同时存在多个，根据您的需求不同的地址可以配置相同或者不同的 CallbackUrlKey。

回调地址是否支持更改或删除？

支持，您可以在控制台开发者中心中进行回调地址的配置。

回调地址配置后多长时间生效呢？

配置完成后立即生效。

为什么客户收到 FlowCallbackStatus 为4（已签署）的回调通知后，又收到了 FlowCallbackStatus 为1（待签署）的通知？

以单方签署的合同为例，FlowCallbackStatus 状态变化一般是由1变为4。少量回调可能因状态变化间隔比较短、重发、或者网络传输等原因，小几率出现到达顺序不一致，建议开发者从代码层面进行适当控制，例如状态更新为4后不能再更新为1。

电子签发送回调时超时时间是多久？

超时时间为5秒。

电子签发送回调失败后，回调最大重试次数是多少？重试机制是怎么样的呢？

回调的最大重试次数是36次；回调重试间隔随次数增加，具体如下：

1 秒、2 秒、3 秒、4 秒、5 秒、10 秒、15 秒、20 秒、25 秒、30 秒、35 秒、40 秒、45 秒、50 秒、55 秒、1 分、2 分、3 分、4 分、5 分、6 分、7 分、8 分、9 分、10 分、15 分、25 分、35 分、45 分、55 分、1 时、2 时、3 时、4 时、5 时、6 时

回调样例

回调请求包（加密）：

POST /callback HTTP/1.1
Host: www.esstest.com
User-Agent: Go-http-client/1.1
Content-Length: 1088
Content-Type: text/plain
Accept-Encoding: gzip

YyYyLZonMceFMFFi5jRnnOWrOasvzmKtGAvRPq1IzuYma88UvTqyZy8QpNVMKxvJY3Sp+NJW6mgTfU35u7SbUon+QCjul1P9P6mcVRuVvYrM2DoFBDgjLURfX+CWnZ9m967nNqiubw9vj9ToysJDZyr0zo4NN1CCfvsyxnVNKhSNbRAy74x4SlLscZ/wcFwdy55S2rBxbjLCqViIj6llQFo74mLHJ8oumngBD1WJZ5ginDNEScPB7+cIHeKF5w3UvUpDqDIUjAj7KFUmIQM8/zY8EafhgCNhWRaGxuFxGF+iMqwC+HJYosbBmrKZ44+8xwL5WlXLx/Cf8bK7J4mJIWbKyul8PBE9Xh8lL/d0Ufnf4sUB0ypbdy/KIr+XQJgFjR2AQGENXvxxlCfdVY5svGfXYaaSSyDND1u9C8kMxQRfNHJye7ulTprROYTtq4GJ8UJQbJbuHvTcppGyMbGO2AvgXcoSogM0JuZzLK/gcPFIWIf9oFTg47M62sLf9YY7UASVITfA5LnE+/1clN4vn748wjS4tdxCL8wjWanPOONTPCMrwH0wsZ86xEf7aLl0/qBWGF13VYh4C4XgiDLtaOs6DdlzMz5EszWISpRRzfJLxcBnhHL9sQu7YWLZzRL6vmP1qtdWZbUYt4Z/eKff5gfmmDGHOxVjd3XhxhfHSdW3a8LzlMT3n69CPBEiOjXA4abshkiT6+hOlJ8uCws+ja2BSmwruqpUn4tq7Je91cT0AhGHuvq9s1VCB7vw8KsVimRHrC6eOa1rgm6qgQNP0fMgGRe+qu4BtfND1a/j9BBuIHQSjLSn2JB2P/EAvbb5J2iPVZj3SppgzhwVCgYUu+osA3LNC4NsYxm/yMs8mq7nOCIZd6D/BM9py5WKS6//e4mM6sY3/S2wOr8snkUsEuu5M35zyRcrCjIaRzV9OKZjP+aqkk2GcF/Figd3N/zCZ+WjC+L9r/ELHn64qEJxZDvXKXVE3dUOchbUPelCb3YO+Mub+76bnvt8IQ2MRf9NaFO7cWlh9mDWkZMXxmOTlxOxQtOeTrW+QywTkZaDGkP83HRjqXd7bn3YBcdFiOy/

此处使用 CallbackUrlKey:"TencentEssEncryptTestKey12345678" ，参考解密代码Demo解密后可获取以下明文

该 CallbackUrlKey 仅用于此处测试样例。

{
  "FlowId": "yDRtrAAAAAAAAAAAAAAAAAAAAAAAAAAA",
  "DocumentId": "yDRtrBBBBBBBBBBBBBBBBBBBBBBBBBB",
  "CallbackType": "sign",
  "FlowName": "测试流程",
  "FlowDescription": "",
  "FlowType": "",
  "FlowCallbackStatus": 4,
  "Unordered": true,
  "CreateOn": 1658892449,
  "UpdatedOn": 1659604019,
  "DeadLine": 1661615999,
  "UserId": "",
  "RecipientId": "yDRtrCCCCCCCCCCCCCCCCCCCCCCCCCCC",
  "Operate": "sign",
  "UserData": "",
  "Approvers": [
    {
      "UserId": "yDRtrDDDDDDDDDDDDDDDDDDDDDDDDDDD",
      "RecipientId": "yDRtrCCCCCCCCCCCCCCCCCCCCCCCCCCC",
      "ApproverType": 1,
      "OrganizationName": "",
      "Required": true,
      "ApproverName": "张三",
      "ApproverMobile": "15912345678",
      "ApproverIdCardType": "ID_CARD",
      "ApproverIdCardNumber": "440300200101010001",
      "ApproveCallbackStatus": 3,
      "ApproveMessage": "",
      "ApproveTime": 1659604019,
      "VerifyChannel": "WEIXINAPP"
    }
  ],
  "CallbackUrl": "https://www.esstest.com"
}