接入指引

开通事件回调

如需开通事件回调能力，请前往 应用回调配置 (opens new window) 进行开通和管理。

第一步：填写服务器配置

企业管理员可以在管理后台配置用于接收腾讯乐享回调请求的服务器URL。配置成功后，企业将得到一个 secret 用于服务器接收请求时验证消息来源合法性。

第二步：验证消息是否来自腾讯乐享

腾讯乐享回调请求的数据格式为 JSON 结构，如消息推送的回调请求数据如下：

{
    "nonce": "f8c593b1-2e80-4662-8e78-f4de18272387",
    "timestamp": 1565250843,
    "sign": "354954e40f7ac183d51cbb85f2fd3290c117f7ba",
    "action": "message/push",
    "attributes": {
        "to_user": "STAFF_ID1|STAFF_ID2",
        "to_department": "",
        "to_tag": "",
        "msg_type": "text",
        "text": {
            "content": "腾讯乐享欢迎您！"
        },
        "to_team": "90b684c0146711ec8afa62e1943b6703"
    },
    "team_setting": {
        "from_team": "90b684c0146711ec8afa62e1943b6703",
        "only_member_received": "0"
    },
    "operator": "StaffID",
    "operator_info": {
        "name": "StaffID"
    }
}

每个回调请求都会带上 nonce, timestamp, sign 三个参数用于验证消息来源是否合法。结合第一步得到的 secret，可使用以下方法验证：

判断 sign == sha1(nonce . secret . timestamp)，若返回 true 则消息来源合法。

重放攻击：部分系统内部由于安全扫描等原因重放乐享的回调请求，可能会导致回调被重复处理，如重复写入数据、重复推送消息等。

处理方案：建议验证完签名(sign)后，再判断 timestamp 是否在当前系统时间的3~5秒内（可根据网络延迟适当调整），并对 nonce 记录到缓存中，设置过期时间跟前面判断的 timestamp 有效时间一致。若缓存中存在 nonce，则代表该请求已接收处理过，不再处理。

第三步：结合业务参数和文档处理请求

回调请求的业务参数包括：action、 attributes、 operator，部分业务回调会包含 is_anonymous

参数说明：

参数	说明
action	员工在腾讯乐享平台上触发的事件类型 并非所有事件都会回调，以目前文档提供的为准
attributes	用户触发的事件具体的内容和属性
operator	触发者StaffID，是否明文展示取决于is_anonymous
is_anonymous	用户是否匿名操作