回调应用配置指南

回调配置

1.什么时候需要回调服务

在集成微伴助手与内部系统时，我们往往需要搭建一个回调服务。回调服务，可以实现：

可以及时获取到状态变化。比如，工单发生变化时，不需要定时去拉取工单对比，而是实时地获取到变化的工单，进行同步。

2.回调服务怎么配置

配置回调服务，需要有三个配置项，分别是：URL, Token, AESKey。

首先，URL为回调服务地址，由开发者搭建（需要满足接口要求，参考第3部分说明），用于接收通知消息或者事件。

其次，Token用于计算签名，由英文或数字组成且长度不超过32位的自定义字符串。开发者提供的URL是公开可访问的，这就意味着拿到这个URL，就可以往该链接推送消息。那么URL服务需要解决两个问题：

如何分辨出是否为微伴助手来源
如何分辨出推送消息的内容是否被篡改

通过数字签名就可以解决上述的问题。具体为：约定Token作为密钥，仅开发者和微伴助手知道，在传输中不可见，用于参与签名计算。微伴助手在推送消息时，将消息内容与Token计算出签名。开发者接收到推送消息时，也按相同算法计算出签名。如果为同一签名，则可信任来源为微伴助手，并且内容是完整的。

如果非微伴助手来源，由于攻击者没有正确的Token，无法算出正确的签名；
如果消息内容被篡改，由于开发者会将接收的消息内容与Token重算一次签名，该值与参数的签名不一致，则会拒绝该请求。

最后，AESKey用于消息内容加密，由英文或数字组成且长度为43位的自定义字符串。由于消息是在公开的因特网上传输，消息内容是可被截获的，如果内容未加密，则截获者可以直接阅读消息内容。若消息内容包含一些敏感信息，就非常危险了。AESKey就是在这个背景基础上提出，将发送的内容进行加密，并组装成一定格式后再发送。

3.开发者服务需要实现以下功能

配置回调服务时，需要能同时支持HttpGet以及HttpPost两种能力，

微伴助手会先判断URL服务是否具备解析微伴助手推送消息的能力。
具体方式是，微伴助手往URL服务上发一条Get请求带签名及密文参数到URL服务上，如果URL服务检查签名通过，并能正确返回密文参数对应的明文字符串，则验证通过。此时在微伴助手的配置就开始生效。
后续的业务请求（比如应用菜单的点击事件，用户消息等），都会类似的方式（签名+密文）向服务URL推送消息。URL服务验证签名通过后，需要将POST数据解密，就可以得到对应的业务消息明文

3.1 支持Http Get请求验证URL有效性

开发者填完3个配置项点击确定，此时微伴助手会向开发者填写的URL地址发起一个Get请求来验证URL的有效性；假设开发者服务的地址为https://api.com/receive_weiban_message

请求地址: https://api.com/receive_weiban_message?msg_signature=8ddba101fe5f9404e6b28e2d6cfb7565c7572d09&timestamp=1639731768&nonce=64390332&echostr=505deLub74lMxyhj6SZk55rjDRxM7lEzVa/8ZFdOUWkkv9kFpNI%2B9c3YLRLDjL%2B1GEIWpvuQSFw2ck2zb0QcAQ%3D%3D

收到请求后开发者需要

1、对URL解码，解析出Get请求的参数，包括消息体签名(msg_signature)，时间戳(timestamp)，随机数字串(nonce)以及微伴助手推送过来的随机加密字符串(echostr)

2、验证签名msg_signature、解密echostr得到明文消息内容reply_echostr；可以直接使用加解密库的验证URL函数

3、响应Get请求，响应内容为上一步得到的明文消息内容reply_echostr

3.2 支持Http Post请求接收业务数据

微伴助手在Post请求失败之后会再发起2次Post请求

请求地址: https://api.com/receive_weiban_message?msg_signature=cee361999ae632f3e4b9f153475930ce0903b7b7&timestamp=1639732244&nonce=741425964

请求参数

{
  "corp_id": "1704174310933890049", 
  "app_id": "100001", 
  "encrypt": "3bVgLZLP6TtC8U5qbXxHoq6bL2ZZyarp0s5lyp5RwqNY6E3mhmCU6sb2UlizgL8sHwFqqEtgpOC1OuHBKXF987LB/l8HSRaRHfYseZ5/9QWOJftb/nnI2t6lsEB5aIDkOv3RuvdOYEsvoPy45v6eCbe8sR3WMvy5YDjBiauLWw9us9xvGFx/aRV3DTjPzf8J6H5u8D5339MUP0I+nM11Mhe9pIFnnWMY6Cbd6g9fpwXKalRWBU4N6LXF2/eMypBuVsvJRAncvergZJoBj3svtc2LbaI70qod/G5OmEtbco5A6BXcoaN9HlszmvYH3XIUS8PyRqBOTaELLgIlSIAtzJEX8J7ZjK65LfgVYY2AZzvxxXkQd/mWHhh90M1HPgGQrCYQSkuRb1jGHgKf4HtWgqFzTY50+YwOmrNY4DAun6jrbLwKweMWNMU7g5Qd3YuEklwnteftmL9iAJxJRnx+EihOR+DZjqWibfRnuhPQLuHkMXLvQIzkD+LHDdOYOaWJ3kXvUwt9BGgLKP9QD/kow6nc6xbnUUI+ELxWo65P9PzrJ0otkh1r59rZiwaUC4FFl8W75dh3EGp8dg3Y2adtfekz3Ok9OxMW07HcVoedYdaapUQh8gozu5LC3VZ3Tmmv8TMY/XhWzj8mWIpI6eE57pWTZT3MANhILBmm/n0HmocqIXALjcllklMWWm0X6Z+HEOaf4DiSGk8bRgl9jgifbG0B+s5hV5+1qBMWLaGBLi4MWClldW6wk1YdonlD3fKl0Uxma0eQSVGFlTMezdcJi+92higQevlEC+xanZ3E4m0=",
  "retry_count": 1
}

参数	说明
corp_id	公司id
app_id	应用id，对于每个公司从100001开始递增
encrypt	密文，解密可得到明文的消息结构体
retry_count	重试次数，值有0、1、2

收到请求后开发者需要

1、对msg_signature签名进行校验; 解密encrypt，得到明文的消息结构体

2、正确响应本次请求，响应的状态码需要为200

明文消息的格式如下

{
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "corp_id": "1704174310933890049",
    "create_time": 1640244967,
    "type": "event",
    "event": "work_order_change",
    "status": "switch",
    "msg_data": {}
}

参数	说明
id	消息id
corp_id	公司id
create_time	消息创建时间，精确到小数点后3位
type	消息类型，值为"event"表示消息为事件类型
event_type	事件类型
status	事件变更类型
msg_data	消息体，不同事件类型消息体不同

3.3 微伴助手服务器的ip段设置为白名单

设置防火墙拦截其他ip地址，将微伴助手服务域名weibanzhushou.com设置为白名单

4.回调服务demo

Python
https://github.com/weiban-open-platform/open-msg-crypt-python

Golang
https://github.com/weiban-open-platform/open-msg-crypt-golang

最后修改时间： 3 年前