回调通知说明
一. 回调说明
| 项目 | 说明 |
|---|---|
| 回调地址 | 在企业应用管理中的企业版应用中配置(配置方式可以参考下方回调 FAQ中的回调地址是否支持更改或删除问题) |
| 请求方式 | 电子签平台的回调都是POST 请求, 如果得到的是GET请求，请确认回调地址是否存在http到https的转发 |
| 数据格式 | JSON格式请求（"Content-Type":"application/json"），数据样式：{"encrypt":"base64后的密文"} |
| 回调成功条件 | 一旦贵方给电子签平台返回httpcode 200, 电子签平台认为回调成功, 将不会再重发回调消息 |
回调地址是否可用的验证方式
如果配置了回调 Url地址，但是没有收到回调通知，贵方可在外网环境用下方curl命令简单, 需要能够正常返回 httpcode 200表示可用 , 如下
curl https://tsign.tencent.com/callback -H 'Content-type: application/json' -X POST -d '{"encrypt":"62KE4r5Wz0yHzEpMOwVRbM1KV0"}'
# 需将https://tsign.tencent.com/callback 换成贵方配置的回调地址
二. 回调场景
通知类型以 MsgType 做区分，按照回调通知类型主要分为：
合同相关回调, 主要是合同状态变动等场景
印章相关回调, 主要是印章操作和印章授权等场景
模板相关回调, 主要是模板操作等场景
企业与员工相关回调, 主要是企业实名或者员工加入企业等场景
文件资源相关回调, 主要是合同合成等场景
三. 回调加密与校验
1.回调通知配置和接收端的代码编写示例（视频）
2. 回调消息加解密
回调加密 key
如果配置了回调加密 key（可选参数），电子签的回调请求体会进行加密处理，需要客户使用配置的回调加密 key进行解密得到真正的回调消息。
注意：配置了回调加密 key即会开启消息加密，去掉即为关闭发送明文回调消息。建议开启加密确保数据安全。
解密步骤
- 对收到的数据
{"encrypt":"base64后的密文"}中的base64后的密文进行 Base64 解码得到原始的密文。 - 对原始的密文进行对称解密，算法为 AES-256-CBC，密钥为腾讯电子签提供的 CallbackUrlKey，IV 取 CallbackUrlKey 值的前 16 位，数据采用 PKCS#7 填充。
- 解密得到的数据为输入参数的 Json 格式。
解密代码可以参考 解密代码 demo
3. 回调消息校验
签名验证 token
如果配置了 签名验证 token（可选参数），电子签的回调请求会在header中附带签名参数[Content-Signature]，客户方用来验证请求来源确实电子签，保证安全性。
原理可参考：https://docs.github.com/en/developers/webhooks-and-events/webhooks/securing-your-webhooks
校验步骤
当贵方回调服务接收到回调时：
取出 header [Content-Signature]
验证签名, 验证代码如下, 如果验证通过，继续处理。如果不通过，忽略该请求
// payload_body 为接收到的消息体内容
// verify_token 为在第三方应用中配置的 "签名验证 token"
// content_signature 为从请求头部中取得的Content-Signature的值
def verify_signature(payload_body,content_signature,verify_token):
signature = 'sha256=' + OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'), verify_token, payload_body)
return halt 500, "Signatures didn't match!" unless Rack::Utils.secure_compare(signature, content_signature)
注意：payload_body为整个原始消息体（即：{"encrypt":"base64后的密文"}），请不要做任何更改。
四. 通用结构体
1. 明文回调消息结构体
如果未设置回调加密 key, 回调服务接收到的请求直接是这个结构体的json序列化
| 参数名称 | 参数类型 | 参数描述 |
|---|---|---|
| MsgId | Sting | 消息唯一ID, 为32为字符串, 用于唯一确定本消息 |
| MsgType | Sting | 消息类型, 标识本消息是那个场景发送的, 如FlowStatusChange标识合同状态变更, 可以参考各个场景的回调 |
| MsgVersion | String | 消息版本，固定为 ThirdPartyApp |
| MsgData | 结构体 | 消息数据, 各个消息类型的结构体不同, 可以参考各个场景的回调中MsgData结构体定义 |
2. 密文回调消息结构体
如果设置了回调加密 key , 回调服务接收到的请求是此密文回调消息结构体的json序列化, 解密后才是明文回调消息结构体json序列化
| 参数名称 | 参数类型 | 参数描述 |
|---|---|---|
| encrypt | String | 加密后的消息体（需通过回调加密 key解密得到明文回调消息结构体json序列化） |
五. 回调 FAQ
回调地址是否支持同时配置多个？
不支持，一个SaaS企业只能有一个回调地址。
回调地址是否支持更改或删除？
支持，您可以在控制台在企业应用管理中的企业应用中配置中进行回调地址的配置。
回调配置后多长时间生效呢？
配置完成后立即生效, 如果修改了回调加密 key 和签名验证 token , 确保回调已经支持新这两个key。
为什么客户收到 ALL(合同签署完成)的回调通知后，又收到了PART(合同签署中)或者INIT(合同创建)的通知？
以单方签署的合同为例，FlowCallbackStatus 状态变化一般是由合同签署中或者合同创建变为合同签署完成。 少量回调可能因状态变化间隔比较短、重发、或者网络传输等原因，小几率出现到达顺序不一致，建议开发者从代码层面进行适当控制，例如状态更新为合同签署完成后不能再更新为合同签署中和合同创建。
电子签发送回调时超时时间是多久？
超时时间为 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 时
如果36次都失败, 电子签平台认为此消息无法回调会丢弃此消息
回调延时多长?
回调会在发生对应事件后立刻执行，涉及处理和网络请求等，一般会在几百毫秒的延时的样子。
具体延时时间取决于网络状况、服务器负载和其他因素。
如果您长时间未收到回调通知，请检查贵方的回调服务是否正常，如果正常的话可以联系客服人员进行处理。
六. 回调样例
1. 回调服务收到加密数据
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=="}
此处使用 回调加密 key: TencentEssEncryptTestKey12345678 ，参考解密代码Demo解密后可获取以下明文：
!该 回调加密 key 仅用于此处测试样例。
{
"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"
}
}
2. 明文回调消息
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
{"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"}}