HTTP回调概述

• 企业内部应用推荐直接通过开发者后台订阅回调事件，详情请参考配置事件订阅。
• 第三方企业应用推荐使用SyncHTTP推送和RDS推送方式订阅回调事件，这两种方式可直接使用推送的数据，配置更简单。详情请参考回调概述。
• HTTP推送的出口IP为203.119.0.0/16 140.205.0.0/16 106.11.0.0/16 198.11.0.0/16。

​

使用场景

• 在你的业务对数据的实时性要求较高时。例如：在新员工入职或者离职时，应用需要第一时间变更用户数据，此时就可以订阅通讯录事件。
• 你的应用需要及时响应用户的操作时。例如：某用户加入某群聊时，应用可以订阅群会话事件，在用户进入群聊的时候，向用户发送欢迎等信息。
• 管理员开通第三方企业应用时，向应用推送企业授权开通应用事件，开发者可以根据推送的corpid进行企业激活和应用开通。

​

HTTP事件回调流程

1. 开发者需要在钉钉开放平台配置HTTP请求接收地址用于接收推送的回调事件。
2. 钉钉会向应用配置的HTTP地址推送回调事件数据包。使用应用创建时开发者在开发者后台填写的应用加解密key来进行加密，开发者填写的应用Token进行签名。详情请参考测试回调URL事件。
3. 应用在收到推送后需要进行验证签名和解密，并且返回包含经过加密的字符串的JSON数据。
4. 调用注册回调事件接口接收回调事件。

​

配置请求地址和事件

1. 登录开发者后台。找到已创建的应用，进入应用详情页。
2. 单击 开发管理，然后单击 修改，推送类型选择 HTTP推送。
3. 配置用于接收请求的HTTP地址。
   • token：钉钉每次向你的地址推送事件数据时都会携带token，用于生成签名、校验回调请求的合法性。必须为英文或数字，长度为3~32个字符。
   • 数据加密密钥：单击 自动生成 生成AES密钥。回调消息内容的加解密参数，是AES密钥的Base64编码，具体使用参见消息加解密。
   • 回调URL：用于接收订阅事件请求的URL。当应用订阅的事件触发时，钉钉会向该网址发送相应的 HTTP POST 请求。 说明 每个应用只能配置一个回调URL，该应用订阅的所有事件通知都会发送到该请求网址。
4. 配置完成后，单击 验证有效性 按钮时，开放平台会向你配置的网址推送一个application/json格式的 POST请求, 用于验证你配置的网址的合法性。请求如下：
   {
       "encrypt":"HJ+q6tp1qhl9L1+++j74xxxx"   //加密字符串，参考下文的加解密说明
   }
   
   当你收到开放平台的POST验证请求时，你需要做解密处理，并在 1500ms 内返回包含 success 的加密字符串（JSON格式）。钉钉开放平台收到返回的JSON信息后会做解密处理，如果可以得到正常的success字符串，则验证回调信息推送正常，否则会判定为失败的回调信息。
5. 成功配置请求地址后，单击右上角 保存。

​

接收并响应事件

• 接收事件信息 当事件发生时，钉钉会主动向配置的HTTP地址发送POST请求，推送对应的事件信息。例如订阅通讯录事件后，当通讯录发生变更时，会向注册的HTTP地址推送事件信息，其格式如下。
  • 请求的URL格式如下：
    http://你注册的HTTP地址?signature=111108bb8e6dbc2xxxx&timestamp=1783610513&nonce=380320111
    
  • 包含的JSON数据如下：
    {
        "encrypt":"1ojQf0NSvw2WPvW7LijxS8UvISr8pdDP+rXpPbcLGOmIBNbWetRg7IP0vdhVgkVwSoZBJeQwY2zhROsJq/HJ+q6tp1qhl9L1+ccC9ZjKs1wV5bmA9NoAWQiZ+7MpzQVq+j74rJQljdVyBdI/dGOvsnBSCxCVW0ISWX0vn9lYTuuHSoaxwCGylH9xRhYHL9bRDskBc7bO0FseHQQasdfghjkl"
    }
    
  其中：
  • signature为消息体签名。
  • timestamp为时间戳。
  • nonce为随机字符串。
  • encrypt为加密的推送事件信息。
• 响应事件信息 针对所有的回调事件，在您收到事件推送后，务必返回包含 success 的加密的字符串给钉钉，只有返回了该数据，钉钉才会判断此事件推送成功。 具体返回给钉钉的数据格式如下：
  {
    "msg_signature":"111108bb8e6dbce3c9671d6fdb69d1506xxxx",
    "timeStamp":"1783610513",
    "nonce":"123456",
    "encrypt":"1ojQf0NSvw2WPvW7LijxS8UvISr8pdDP+rXpPbcLGOmIxxxx"
   }
  
  其中：
  • msg_signature为消息体签名。
  • timeStamp为时间戳。
  • nonce为随机字符串。
  • encrypt为success加密字符串。

​

消息加解密

• random 为16字节的随机字符串。
• msg_len 为4字节的msg长度，网络字节序。
• msg 为消息体明文。
• key 为应用的suiteKey。

• 对密文BASE64解码：aes_msg=Base64_Decode(encrypt)；
• 使用AESKey做AES解密：rand_msg=AES_Decrypt(aes_msg)；

public Map<String, String> callBack(HttpServletRequest request,
                                    @RequestParam(value = "msg_signature", required = false) String msg_signature,
                                    @RequestParam(value = "timestamp", required = false) String timeStamp,
                                    @RequestParam(value = "nonce", required = false) String nonce,
                                    @RequestBody(required = false) JSONObject json) {
    try {
        // 1. 从http请求中获取加解密参数

        // 2. 使用加解密类型
        // Constant.OWNER_KEY 说明：
        // 1、开发者后台配置的订阅事件为应用级事件推送，
        //      此时OWNER_KEY为应用的APP_KEY（企业内部应用）或SUITE_KEY（三方应用）。
        // 2、调用订阅事件接口订阅的事件为企业级事件推送，
        //      此时OWNER_KEY为：企业的CORP_ID（企业内部应用）或SUITE_KEY（三方应用）
        DingCallbackCrypto callbackCrypto = new DingCallbackCrypto(Constant.AES_TOKEN, Constant.AES_KEY, Constant.OWNER_KEY);
        String encryptMsg = json.getString("encrypt");
        String decryptMsg = callbackCrypto.getDecryptMsg(msg_signature, timeStamp, nonce, encryptMsg);

        // 3. 反序列化回调事件json数据
        JSONObject eventJson = JSON.parseObject(decryptMsg);
        String eventType = eventJson.getString("EventType");

        // 4. 根据EventType分类处理
        if ("check_url".equals(eventType)) {
            // 测试回调url的正确性
            bizLogger.info("测试回调url的正确性");
        } else if ("user_add_org".equals(eventType)) {
            // 处理通讯录用户增加事件
            bizLogger.info("发生了：" + eventType + "事件");
        } else {
            // 添加其他已注册的
            bizLogger.info("发生了：" + eventType + "事件");
        }

        // 5. 返回success的加密数据
        Map<String, String> successMap = callbackCrypto.getEncryptedMap("success");
        return successMap;

    } catch (DingTalkEncryptException e) {
        e.printStackTrace();
    }
    return null;
}

{
    "EventType": "user_add_org",
    "TimeStamp": 43535463645,
    "UserId": [
        "user1",
        "user2"
    ],
    "CorpId": "dinge8a56572f80b02a8ffexxxx"
}

​

相关链接

• 事件列表