钉钉开发文档

验证回调有效性

更新时间: 2018-6-21

名词解释
回调

开发者在创建完应用后,在开发者后台-应用首页点击“设置回调-设置”,填写回调地址并验证回调地址有效性(若验证不成功,正式应用将不能进行开通,而测试应用可以开通),如下图所示:
17_17_27__03_29_2018.jpg

开发者点击点击“验证有效性”时,钉钉服务器对回调地址推送"验证回调URL有效性事件",应用收到推送后需要返回“success”的加密值。

回调事件处理步骤

角色 ACTION
钉钉 向ISV的回调URL推送加密消息
应用 解密消息并解析事件类型
应用 针对不同事件类型处理业务逻辑(例如验证回调事件:check_create_suite_url)
应用 返回“success”的加密值【JSON数据格式】

代码逻辑示例

验证回调URL有效性在ISV服务端接收消息的处理代码逻辑(Java代码示例):

try {
         // 创建加解密类
         // 第一个参数为创建应用之时填写的token
         // 第二个参数为创建应用之时生成的数据加密密钥(ENCODING_AES_KEY)
         // 第三个参数,传入应用的suiteKey
         // 具体参数值请查看开发者后台(//open-dev.dingtalk.com)
         // 注:其中,对于第三个参数,在第一次接受『验证回调URL有效性事件的时候』
         // 传入Env.CREATE_SUITE_KEY,对于这种情况,已在异常中catch做了处理。
         //  
        dingTalkEncryptor = new DingTalkEncryptor(Env.TOKEN, Env.ENCODING_AES_KEY, Env.SUITE_KEY);
         // 
         // 获取从encrypt解密出来的明文
         // 
        plainText = dingTalkEncryptor.getDecryptMsg(msgSignature, timeStamp, nonce, encrypt);
    } catch (DingTalkEncryptException e) {
        // TODO Auto-generated catch block
        dingTalkEncryptException = e;
        e.printStackTrace();
    } finally {
 
    }
 
    // 
    //  对从encrypt解密出来的明文进行处理
    //  不同的eventType的明文数据格式不同
    // 
 
    JSONObject plainTextJson = JSONObject.parseObject(plainText);
    String eventType = plainTextJson.getString("EventType");
    // res是需要返回给钉钉服务器的字符串,一般为success
    // "check_create_suite_url"和"check_update_suite_url"事件为random字段
    // 具体请查看文档或者对应eventType的处理步骤
    // 
    String res = "success";
 
    switch (eventType) {
        case "check_create_suite_url":
            //可返回表明服务端“收到了”的字段
            break;
    }
 
    //  对返回信息进行加密
    long timeStampLong = Long.parseLong(timeStamp);
    Map<String, String> jsonMap = null;
    try {
        // 
        // jsonMap是需要返回给钉钉服务器的加密数据包
        // 
        jsonMap = dingTalkEncryptor.getEncryptedMap(res, timeStampLong, nonce);
    } catch (DingTalkEncryptException e) {
        System.out.println(e.getMessage());
        e.printStackTrace();
    }
    JSONObject json = new JSONObject();
    json.putAll(jsonMap);
    response.getWriter().append(json.toString());

应用的URL有效性验证逻辑中需要的参数例如:suiteKey、数据加密密钥(EncodingAESKey)、token等信息,需要配置到代码中。参考QuickStart服务端demo代码CallbackController

回调URL说明

字段 属性
回调URL 以http:// 或 https:// 开头,系统将会把此应用的suiteTicket,临时授权码以及授权变更等事件等推送给此URL,详细请看回调协议

开发者需要将开发者后台中设置的token、suiteKey、数据加密密钥配置到示例demo中的配置文件中,再点击“验证回调URL有效性”方可验证生效。

回调的URL参数

开发者点击“验证URL的有效性”后,钉钉服务器将如下参数追加到回调URL上:

字段 属性
signature 加密签名
timestamp 时间戳
nonce 随机数

钉钉向回调地址POST数据解密后示例

{

  "EventType":"check_create_suite_url",
  "Random":"brdkKLMW"

}

回调数据参数说明

参数 说明
Random 随机字符串
EventType check_create_suite_url

开发者通过检验signature对请求进行校验(下面有校验方式)。若确认此次请求来自钉钉服务器,在接收到推送之后,需要返回“success”的加密值,加密方案请参考:消息体加密解密

应用返回参数说明

应用收到消息后返回给钉钉服务器的数据参数说明

参数 说明
msg_signature 消息体签名
timeStamp 时间戳
nonce 随机字符串
encrypt "success"字段的加密字符串

温馨提示:
为了快速体验测试应用开发流程,您应该创建测试应用,暂时不处理回调事件,此种情况可以暂时忽略本小节,待需要用到回调逻辑/或者创建正式应用时仔细查看,确保回调验证成功。
另外,如果您需要在没有公网IP或域名的服务器上(比如您自己的办公电脑)调试回调URL,可借助内网穿透工具映射一个可公网访问的地址,注意仅用于测试开发阶段。