企业在开发回调服务时,仅支持 HTTP 和 HTTPS 两种协议,且需要同时支持 HTTP GET 和 HTTP POST 两种能力。
在事件订阅配置时,腾讯会议会先校验 URL 服务是否具备解析腾讯会议回调消息的能力。具体方式为:腾讯会议向企业回调 URL 服务发送一条 GET 请求,GET 请求中带有 base64 编码后的验证参数及 Header 中带校验签名需要的参数,如果 URL 服务检查签名通过并能正确返回解码后的验证参数,HTTP 头部响应200,才能验证通过。
后续的事件回调(例如会议创建、会议更新等)都会运用 POST 请求以类似上述的方式向 URL 推送消息,URL 服务验证签名通过后,需要将 POST 请求 Body 中的 data 数据进行 base64 解码再用加密密钥解密后才能得到对应的明文数据。
支持 HTTP GET 请求验证 URL 有效性
假定企业接收事件消息回调的 URL 为:
http://api.company.com
。在配置事件订阅时,腾讯会议会发送验证消息到填写的 URL,请求内容如下:
调用方法:GET
请求地址:
http://api.company.com?check_str=CHECK_STR
URL 参数说明
参数名称 | 参数类型 | 参数描述 |
check_str | String | 先经过加密密钥加密,再 base64 编码后用于校验的字符串(需要进行 Urldecode 处理)。 |
Header 参数说明
参数名称 | 参数类型 | 参数描述 |
timestamp | String | 时间戳,与 nonce 结合使用,用于签名校验。 |
nonce | String | 随机数,与 timestamp 结合使用,用于签名校验。 |
signature | String |
验证 URL 有效性
回调服务需要作出正确的响应才能通过 URL 验证,具体操作如下:
1. 对收到的请求,解析上述的各个参数值。
注意:
参数值需要进行 Urldecode 处理。
2. 根据已有的 token,结合上述 timestamp、nonce、check_str 参数计算签名,并与 signature 参数对比是否一致,一致表示调用合法,签名计算方法请参见 签名校验。
3. 对 check_str 参数先进行 base64 解码,再用加密密钥解密后得到原始明文字符串,事件加解密方法参见 事件加解密。
4. 在3秒内响应 GET 请求,响应内容为上一步得到的明文字符串。
注意:
响应内容不能加引号、换行符等,否则配置事件订阅时将保存失败。
支持 HTTP POST 请求接收事件消息回调
假定企业接收事件消息回调的 URL 为:
http://api.company.com
。当事件触发时,腾讯会议会发送回调消息到填写的 URL,请求内容如下:
调用方法:POST
Content-Type:application/json
请求地址:
http://api.company.com
Body 数据格式
{"data":"eyJldmVudCI6Im1lZXRpbmcuY3JlYXRlZCIsInVuaXF1ZV9zZXF1ZW5jZSI6ImYyMDA5NmVlLThhYzgtNGRmMi1hN2RlLTA1NzQ2NDlmMjExYiIsInBheWxvYWQiOlt7Im9wZXJhdGVfdGltZSI6IjIwMjAtMTItMjkgMTc6NDE6MDYiLCJvcGVyYXRvciI6eyJ1c2VyaWQiOiJ0ZXN0ZXIwMDAwNmJhNWJhYjMzOTg1OGMxM2M5MzBjY2E5NTY4NCJ9LCJtZWV0aW5nX2luZm8iOnsibWVldGluZ19pZCI6IjYwNTg4OTAzODU0ODA5MjEwNTIiLCJtZWV0aW5nX2NvZGUiOiI1MzA4MTI0NTIiLCJzdWJqZWN0IjoibWVkaWEgdGVzdGVyIG1lZXRpbmciLCJjcmVhdG9yX2lkIjoidGVzdGVyMDAwMDZiYTViYWIzMzk4NThjMTNjOTMwY2NhOTU2ODQiLCJob3N0cyI6WyJ0ZXN0ZXIwMDAwNmJhNWJhYjMzOTg1OGMxM2M5MzBjY2E5NTY4NCJdLCJtZWV0aW5nX3R5cGUiOjAsInN0YXJ0X3RpbWUiOiIyMDIwLTEyLTI5IDE3OjQxOjA0IiwiZW5kX3RpbWUiOiIyMDIwLTEyLTI5IDE4OjAxOjA0In19XX0"}
Body 参数说明
参数名称 | 参数类型 | 参数描述 |
data | String | 先经过加密密钥加密后,再 base64 编码后的事件回调数据,解码后的字段解释请查看会议事件相关文档。 |
Header 参数说明
参数名称 | 参数类型 | 参数描述 |
timestamp | String | 时间戳,与 nonce 结合使用,用于签名校验。 |
nonce | String | 随机数,与timestamp 结合使用,用于签名校验。 |
signature | String |
验证 URL 有效性
企业接收到回调请求后,需要做如下处理:
1. 对 signature 进行校验。
2. 对 data 先进行 base64 解码,再用加密密钥解密后,得到明文数据,事件加解密方法参见 事件加解密。
3. 正确响应本次请求:
腾讯会议在5秒内接收不到响应则会断掉连接,并分别会在1分钟、3分钟、6分钟后重新发起请求,会重试三次。
当响应的 HTTP 头部返回200且响应内容为 successfully received callback 字符串(不能加引号、换行符),则表示回调成功,其他情况一律当做失败并也会在1分钟、3分钟、6分钟后重新发起请求,重试三次。
成功响应内容的 go 语言代码示例:
http.Response().Write([]byte("successfully received callback"))