配置事件订阅

​

使用场景

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

​

事件订阅流程

​

配置请求地址和事件订阅

1. 登录开发者后台，找到已创建的企业内部应用。
2. 单击 事件订阅，然后单击编辑配置用于接收请求的HTTP地址。 注意 确保该地址公网可以访问。 编辑完请求地址，单击 保存 按钮时，开放平台会向你配置的网址推送一个 application/json 格式的 POST 请求, 用于验证你配置的网址的合法性。请求如下：
   {
       "encrypt": "ajls384kdjx98XX" // 加密字符串，解密方法请看下方的消息加解密
   }
   
   当你收到开放平台的POST验证请求时，你需要做解密处理，并在 1500ms 内返回包含 success 的加密字符串（JSON格式）。钉钉开放平台收到返回的JSON信息后会做解密处理，如果可以得到正常的success字符串，则验证回调信息推送正常，否则会判定为失败的回调信息。
3. 成功配置请求地址后，在 事件订阅 列表区域，开启要订阅的事件。

​

接收并响应事件

• 接收事件信息 当事件发生时，钉钉会主动向配置的HTTP地址发送POST请求，推送对应的事件信息。例如订阅通讯录事件后，当通讯录发生变更时，会向注册的HTTP地址推送事件信息，其格式如下。 说明 钉钉服务器推送信息是即时推送，如果企业的回调地址没有在1500毫秒内返回正确的加密信息给钉钉服务器，钉钉服务器会判断为推送失败。 请求的URL格式如下：
  http://你注册的HTTP地址?signature=111108bb8e6dbc2xxxx&timestamp=1783610513&nonce=380320111
  
  包含的JSON数据如下：
  {
      "encrypt":"1ojQf0NSvw2WPvW7LijxS8UvISr8pdDP+rXpPbcLGOmIBNbWetRg7IP0vdhVgkVwSoZBJeQwY2zhROsJq/HJ+q6tp1qhl9L1+ccC9ZjKs1wV5bmA9NoAWQiZ+7MpzQVq+j74rJQljdVyBdI/dGOvsnBSCxCVW0ISWX0vn9lYTuuHSoaxwCGylH9xRhYHL9bRDskBc7bO0FseHQQasdfghjkl"
  }
  
  其中：
  • signature为消息体签名。
  • timestamp为时间戳。
  • nonce为随机字符串。
  • encrypt为加密的推送事件信息。
• 响应事件信息 当你收到开放平台的POST验证请求时，你需要做解密处理，并在 1500ms 内返回包含 success 的加密字符串（JSON格式）。钉钉开放平台收到返回的JSON信息后会做解密处理，如果可以得到正常的success字符串，则验证回调信息推送正常，否则会判定为失败的回调信息。 具体返回给钉钉的数据格式如下： 注意 返回的数据格式必须是JSON格式。
  {
    "msg_signature":"111108bb8e6dbce3c9671d6fdb69d1506xxxx",
    "timeStamp":"1783610513",
    "nonce":"123456",
    "encrypt":"1ojQf0NSvw2WPvW7LijxS8UvISr8pdDP+rXpPbcLGOmIxxxx"
   }
  
  其中：
  • msg_signature为消息体签名。
  • timeStamp为时间戳。
  • nonce为随机字符串。
  • encrypt为success加密字符串。

​

消息加解密

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

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

• 此代码示例的加解密过程依赖 DingCallbackCrypto 工具类，参见dingtalk-callback-Crypto。
• 示例中的Constant.OWNER_KEY说明如下：
  • 当使用本文档中的方式接收钉钉推送的订阅事件时，是以应用为维度推送的，OWNER_KEY为应用的AppKey，可在开发者后台的应用详情页面中获取。
  • 当使用HTTP回调注册接口方式接收钉钉推送的订阅事件时，是以企业为维度推送的，OWNER_KEY为CorpId。

public Map<String, String> callBack(
                                    @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。
        // 2、调用订阅事件接口订阅的事件为企业级事件推送，
        //      此时OWNER_KEY为：企业的appkey（企业内部应用）或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"
}

​

常见问题

• 问题描述 点击保存，页面报错“HTTP请求结果校验返回字段值失败”，如下图所示。
• 原因
  • 返回给钉钉服务器的json信息中有其中一个字段值不正确。
  • 返回给钉钉服务器的信息不是json格式。
• 解决方案 构造main方法，使用回调地址返回的四个字段值，调用加密接口，验证得到的值是否为success字符串。 例如：
  //构造加解密类，使用的参数不变
  DingTalkEncryptor dingTalkEncryptor = new DingTalkEncryptor("123456", "1234567890123456789012345678901234567890123", "dingsnotzck6pm5veliw");
  //加密方法内传你的回调地址返回给钉钉服务器的四个参数
  String result = dingTalkEncryptor.getDecryptMsg("9a95a004dd16f5c307e849b994173f76aa26e5eb", "1614767836", "A7Co0cJLMzIDtMMI", "YvkvaGe4hQxd3VxRmEty0dVlnCOAqwf56xwTRHDHoOURqhalbmBJQk5FNcRk42Gl5T0YQXZNwpwWSm1xAFJ5ZA==");
  System.out.println(result);
  
  此时的运行结果如下：
  • 如果得到了success字符串，说明返回的值没有问题，问题出现在回调接口返回给钉钉服务器的值参数格式不对，需要再次确认。
  • 如果运行出现报错，常见运行报错和原因如下：

    错误	原因	调整方式
    计算解密文字corpid不匹配	DingTalkEncryptor中OWNER_KEY参数错误。	当前开发者后台应用上的事件订阅，owner_key需要传当前应用的appkey值。
    不合法的aes key	DingTalkEncryptor中ENCODING_AES_KEY参数错误。	ENCODING_AES_KEY自定义的固定43位字符串，只支持大小写字母和数字。
    签名计算失败	解密方法中的参数使用有问题。	解密方法getEncryptedMap内的四个参数都来自钉钉服务器请求时带来的值。