回调通知能力V2
功能介绍
2023年5月15日之后注册的企业，将默认使用回调通知V2
通过回调通知，您可以在合同状态产生变化以及发生印章、模板、员工相关操作等场景接收到来自电子签的回调通知。
如您需要使用此功能，需提供能接收并处理 HTTP POST 请求的回调地址，请确保该地址提供的服务可公网访问并能正常处理回调通知。
电子签推送的回调内容有进行加密处理，在接收到回调通知后需用配置好的 Key 进行解密。
配置回调地址
登录 腾讯电子签控制台 在集成管理中，选择生产运行（如果当前为测试环境，请选择测试联调）。
在参数配置中设置回调地址，请确保填入的地址能够接收并处理 HTTP POST 请求，并返回状态码200表示处理正常。
选择点击系统生成可以随机生成解密的Key(图中签名验证token实际就是解密key，待改版后修改文案)。
还可以生成token，用于回调签名验证。 此处支持配置多个回调地址并同时生效。
支持的回调场景
- 合同发起以及签署相关回调
- 印章相关回调
- 模板相关回调
- 企业与员工相关回调
回调加密与通知校验
回调消息加解密
- 对收到的数据进行 Base64 解码得到密文。
- 对密文进行对称解密，算法为 AES-256-CBC，密钥为腾讯电子签提供的 CallbackUrlKey，IV 取 CallbackUrlKey 值的前16位，数据采用 PKCS#7 填充。
- 解密得到的数据为输入参数的 Json 格式。
解密代码可以参考 解密代码Demo
回调通知校验
配置回调地址的时候，如果配置了“回调签名验证TOKEN（可选参数）”，
电子签的回调请求会在header中附带签名参数[Content-Signature]，客户方用来验证请求来源确实电子签，保证安全性。
原理可参考：https://docs.github.com/en/developers/webhooks-and-events/webhooks/securing-your-webhooks
当接收到回调时：
取出header [Content-Signature]
验证签名
def verify_signature(payload_body)
signature = 'sha256=' + OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'), ENV['SECRET_TOKEN'], payload_body)
return halt 500, "Signatures didn't match!" unless Rack::Utils.secure_compare(signature, request.env['Content-Signature'])
end
- 如果验证通过，继续处理。如果不通过，忽略该请求
回调通用结构体
解密后的结构体（Json）
| 参数名称 | 参数类型 | 参数描述 |
|---|---|---|
| MsgId | string | 消息唯一Id |
| MsgType | string | 消息类型 |
| MsgVersion | string | 消息版本，自建应用集成固定为 CustomApp |
| MsgData | json | 消息数据 |
加密的结构体（Json）
| 参数名称 | 参数类型 | 参数描述 |
|---|---|---|
| encrypt | string | 加密后的消息体（通过CallbackKey解密后得到上面的结构体） |
回调 FAQ
回调地址是否支持同时配置多个？
支持，回调地址可以同时存在多个，根据您的需求不同的地址可以配置相同或者不同的 CallbackUrlKey、token。
回调地址是否支持更改或删除？
支持，您可以在控制台开发者中心中进行回调地址的配置。
回调地址配置后多长时间生效呢？
配置完成后立即生效。
为什么客户收到 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: xxx
Content-Type: application/json
Accept-Encoding: gzip
{"encrypt":"62KE4r5Wz0yHzEpMOwVRbM1KV0pPjj+cmJkT+i65MMscgfHAdNP+9K0nV/fFw1xriwi08APc/wM0mHprE43Hc91VPhRDnu2Wn0+bjzgjmy/FgZKZATR9oquy0/BCWu4C77AjkpkoU1/E7gGLr8M9u9t7zbS4AkkGK5xL5TtwI0sS+CMygmyV7bRjxebMycI52U3QJiwDRIPxFO+7yqeXYXV9AQrRskpCDBNFGW72bh+Ixw9dtX00kWcwVQ93V+mayrvdQ8oGSsL32m72kbBfahsIvIxSYSdDAEeTyokqKGfaLWD27vm55QG218IFKEsOJFDGdqCF+IBcM/+rOFeOrewvP5ehIO2KjFBecTDn0RQTlIiokXIQ4zJKvu6njePFRFoFCZjd4oiEIVn/OBw+rjXml3qwgVBQjPRtYdvDJFNENlVjlkVVmLWeS8MIdqsFWhm6Sa7O8X57mwc0cLJ22mGbyVEzNTFqeFJ/mkueW0leLcoZdjv/+IxZusqa1cpfwzkZhwi5rY6kJffNkkrxIc6OeRvpU4ECgBe/b+kxX+ObC0z9u7nzoZAOHx4akYviyIU5B1romjdfHQ/wDr5udm4Rl4NBhU/6V06Rvaadw0Ta9oBkZHGNxFWv32MnL7fVA0zVNOFDP8n+kaQiNGFAXLF4F5oIItYc5+Gp/IxfkltEki7ni7LztViE7b/ZiKSM+gzQn6fLsJ/dlUoZmh141Y0V/GPpsbxBOnWCjBZdNkLTKxdKCMScLCTysJxv7l6Swff8nAEurbzx1tvyhJAvUDnIaLyP8pRPRFq8p0xm3ZVpOo9k7A952XxVHSs40g4sr/Dihkn60aVhGtKK9DueCzn8P3cWG4TYc03M1hNlPfF+UAfnvQ1ZYAMKT/XPLqYtgRFpRkK96YfVecIrfUe9MjWl0/g4hYCAAOJurFoeGwkJiyQ8Q7DCI5EaHa3s/vI621yQyytC6D2u86RiDJxMW0PdvkUfayT7iPwC83EsfEzpQXr0yeSCQCSBgNByEuCNnZl8LAhYl05Y9+bgCzSPt6EUvmaXclYL+/EPrEmi+hzIdXUwBfhXgICT8MteJgMSgmJM2FjjGxy6uZtfHKRIzf1wk6OORPkPJtMgjlMtMs6VFC62EEeo5Xy2v1S95WT/WQ0tnGR8KjbNnmjNSRyD8VtS2mjlLXaK0xRb71YGt57O19YxQQ3R/Hq9zGqOjG+Agdl+pcvh47RlF8o3CnlU7Q=="}
此处使用 CallbackUrlKey:"TencentEssEncryptTestKey12345678"，参考解密代码Demo解密后可获取以下明文：
!该 CallbackUrlKey 仅用于此处测试样例。
{
"MsgId":"yDwgKUUckp1jouutUymITAlB0ZirQWfm",
"MsgType":"FlowStatusChange",
"MsgVersion":"CustomApp",
"MsgData":{
"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"
}
}