回调模式使用说明

---

概述

在知音楼回调模式下，企业可以接收知音楼下发的数据。接收的信息使用 JSON 数据格式、UTF8 编码，并以 AES 方式加密。

在管理端开启并设置好相关参数后，此应用的回调模式才生效。

针对加解密的处理，知音楼目前只提供 PHP 的语言库，点击下载

开启回调模式

知音楼机构后台-进行开启或关闭

当企业开启应用的回调模式时，企业管理后台要求你填写应用的 URL、Token、EncodingAESKey 三个参数。

URL 是企业接收知音楼消息推送请求的访问协议和地址，支持 http 或 https 协议。

Token 可由企业任意填写，用于生成签名。

EncodingAESKey 用于消息体的加密，是 AES 密钥的 Base64 编码。

验证 URL 有效性

当提交以上信息时，知音楼发送 GET 请求到填写的 URL 上，GET 请求携带四个参数，企业在获取时需要做 urldecode 处理， 否则会验证不成功。

参数	描述	是否必传
msg_signature	知音楼加密签名，msg_signature 结合了企业填写的 token、请求中的 timestamp、nonce 参数、加密的消息体	Y
timestamp	时间戳	Y
nonce	随机数（msgid）	Y
echostr	加密的随机字符串，以 msg_encrypt 格式提供。需要解密并返回 echostr 明文，解密后即为 echostr 明文	首次校验时必带

企业通过参数 msg_signature 对请求进行校验，如果确认此次 GET 请求来自知音楼，那么 企业应该对 echostr 参数解密并原样返回 echostr 明文(不能加引号，不能带换行符)， 则接入验证生效，回调模式才能开启。

后续回调企业时都会在请求 URL 中带上以上参数（echostr 除外），校验方式与首次验证 URL 一致。

使用回调模式

知音楼在回调企业 URL 时，会对消息体本身做 AES 加密，以 JSON 格式 POST 到企业的 URL 上。

知音楼服务器在五秒内收不到响应会断掉连接，并且重新发起请求，进行重试，总共重试六次(30s|60s|300s|600s|1800s|3600s)。如果在调试中，发现成员无法收到响应的消息，可以检查是否消息处理超时。

当接收成功后，http 头部返回 200 表示接收 ok，其他错误码一律当做失败并发起重试 关于重试的消息排重，可以通过 msg_id 排重。

示例: 请求企业回调地址: http://api.xxx.com/xxx?msg_signature=ee2f636ea9722bb45e6d2a7cfd643e7a4010d428&timestamp=1639714105&nonce=1639714105

Header:

content-type: application/json; charset=utf-8
requestId: 163971410544444444444444444

RequestBody:

{
  "Encrypt": "eU9sTThvMDhrV1JZOFpVUTFQLzViV0RlMmREOHVyNWxNTit3QUFmNnhVWE5BY21ZL25IQVBKNXZBNFhycXJPWXgrT2NwUWdERVJMamdNemsxeXA1V2NuK005ZGhUMmNmNnBHWEpqc29qSDZoWWIzRnVhS2N2VlNYZDE3WjgreWtVR1hTVnJKSVJwZFlscTdUWDUvYVVobzMrK3dsemxKcU9FOW8wT25Iek9KTTVhQ3dkeFI1dU9HaEhJVWFqRlR6dE1PYUxPWDZIa2EzU2R0eHhQYkFWbkUvU29rbEJnZzBlek9vZGZ5TUtjcXlLMFI3Ny85Nm5SRStNT1V1UElYSVM0TlNBY0dMdGdiYTZFK3JxdjJ6WklNSGR1aFZ5K0s4OTdTaEMyUWlCRm8zdnU0SkZqdXpla3AzSGxaTUtFc09nM0VyMTBRTG9QZWthMTRVSkVxTmR1TzFwY3RISDdDOXZpMVBiWE9xNGtJPQ==",
  "MsgSignature": "ee2f636ea9722bb45e6d2a7cfd643e7a4010d428",
  "TimeStamp": 1639714105,
  "Nonce": 1639714105
}

1.企业需要对 msg_signature 进行签名校验，保证来源是知音楼，之后再解析出 Encrypt 的内容

2.Encrypt 为加密后的字符串，解析后 手机号修改示例:

{
  "action_type": "userChangeMobile",
  "data": {
    "user_id": 11965,
    "work_code": 11965,
    "name": "ldj",
    "uuid": "4314321412412412",
    "old_mobile": "18211111111",
    "old_phone_area_code": "+86",
    "new_mobile": "18222222222",
    "new_phone_area_code": "+8",
    "cp_id": "1"
  }
}

参数	名称	备注
action_type	消息类型	userChangeMobile:修改手机号
其他事件待补充
data	数据内容	action_type 不同，data 里的内容可能不同，具体参考下面不同的业务消息推送