钉钉开发文档

回调管理

更新时间: 2019-5-23

注册业务事件回调接口

注册回调接口时,钉钉服务器会向URL发起【测试回调URL】事件,来验证填写url的合法性,url服务器需要在接收到回调之后返回字符串“success”的加密json数据,才能完成注册。

请求方式:POST(HTTPS)
请求地址https://oapi.dingtalk.com/call_back/register_call_back?access_token=ACCESS_TOKEN
请求包结构体

{
    "call_back_tag": ["user_add_org", "user_modify_org", "user_leave_org"],
    "token": "123456",
    "aes_key": "1234567890123456789012345678901234567890123",
    "url":"http://test001.vaiwan.com/eventreceive"
}

参数说明

参数 参数类型 必须 说明
access_token String 调用接口凭证
call_back_tag Array[String] 需要监听的事件类型
token String 加解密需要用到的token,ISV(服务提供商)推荐使用注册套件时填写的token,普通企业可以随机填写
aes_key String 数据加密密钥。用于回调数据的加密,长度固定为43个字符,从a-z, A-Z, 0-9共62个字符中选取,您可以随机生成,ISV(服务提供商)推荐使用注册套件时填写的EncodingAESKey
url String 接收事件回调的url,必须是公网可以访问的url地址

SDK请求示例(JAVA)

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/call_back/register_call_back");
OapiCallBackRegisterCallBackRequest request = new OapiCallBackRegisterCallBackRequest();
request.setUrl("http://test001.vaiwan.com/eventreceive");
request.setAesKey("1234567890123456789012345678901234567890123");
request.setToken("123456");
request.setCallBackTag(Arrays.asList("user_add_org", "user_modify_org", "user_leave_org"));
OapiCallBackRegisterCallBackResponse response = client.execute(request,accessToken);

返回结果

{
    "errcode": 0,
    "errmsg": "ok"
}

测试回调URL

在您注册事件回调接口的时候,钉钉服务器会向您“注册回调接口”时候上传的url(接收回调的url)推送一条消息,用来测试url的合法性。收到消息后,需要返回经过加密后的字符串“success”的json数据,否则钉钉服务器将认为url不合法。
POST数据解密后示例:

{
    "EventType" : "check_url"
}
参数 说明
EventType “check_url”

返回给钉钉的数据说明:

{
  "msg_signature":"111108bb8e6dbce3c9671d6fdb69d15066227608",
  "timeStamp":"1783610513",
  "nonce":"123456",
  "encrypt":"1ojQf0NSvw2WPvW7LijxS8UvISr8pdDP+rXpPbcLGOmIBNbWetRg7IP0vdhVgkVwSoZBJeQwY2zhROsJq/HJ+q6tp1qhl9L1+ccC9ZjKs1wV5bmA9NoAWQiZ+7MpzQVq+j74rJQljdVyBdI/dGOvsnBSCxCVW0ISWX0vn9lYTuuHSoaxwCGylH9xRhYHL9bRDskBc7bO0FseHQQasdfghjkl"
  }
参数 说明
msg_signature 消息体签名
timeStamp 时间戳
nonce 随机字符串
encrypt 字符串“success”加密值,具体参考加解密文档

查询事件回调接口

请求方式:GET(HTTPS)
请求地址https://oapi.dingtalk.com/call_back/get_call_back?access_token=ACCESS_TOKEN
参数说明:

参数 参数类型 必须 说明
access_token String 调用接口凭证

SDK请求示例(JAVA)

DingTalkClient  client = new DefaultDingTalkClient("https://oapi.dingtalk.com/call_back/get_call_back");
OapiCallBackGetCallBackRequest request = new OapiCallBackGetCallBackRequest();
request.setHttpMethod("GET");
OapiCallBackGetCallBackResponse response = client.execute(request,accessToken);

返回结果

{
    "errcode": 0,
    "errmsg": "ok",
    "call_back_tag": ["user_add_org", "user_modify_org", "user_leave_org"],
    "token": "123456",
    "aes_key": "",
    "url":"www.dingtalk.com" 
}
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
access_token 调用接口凭证
call_back_tag 需要监听的事件类型
token 加解密需要用到的token,ISV(服务提供商)推荐使用注册套件时填写的token,普通企业可以随机填写
aes_key 数据加密密钥。用于回调数据的加密,长度固定为43个字符,从a-z, A-Z, 0-9共62个字符中选取,您可以随机生成,ISV(服务提供商)推荐使用注册套件时填写的EncodingAESKey
url 接收事件回调的url

更新事件回调接口

请求方式:POST(HTTPS)
请求地址https://oapi.dingtalk.com/call_back/update_call_back?access_token=ACCESS_TOKEN
请求包结构体

{
    "call_back_tag": ["user_add_org", "user_modify_org", "user_leave_org","org_admin_add", "org_admin_remove", "org_dept_create", "org_dept_modify", "org_dept_remove", "org_remove"],
    "token": "123456",
    "aes_key": "11111111lvdhntotr3x9qhlbytb18zyz5z111111111",
    "url": "http://buyang001.vaiwan.com/eventreceive"
}

参数说明

参数 参数类型 必须 说明
access_token String 调用接口凭证
call_back_tag Array[String] 需要监听的事件类型
token String 加解密需要用到的token,ISV(服务提供商)推荐使用注册套件时填写的token,普通企业可以随机填写
aes_key String 数据加密密钥。用于回调数据的加密,长度固定为43个字符,从a-z, A-Z, 0-9共62个字符中选取,您可以随机生成,ISV(服务提供商)推荐使用注册套件时填写的EncodingAESKey
url String 接收事件回调的url

SDK请求示例(JAVA)

DingTalkClient  client = new DefaultDingTalkClient("https://oapi.dingtalk.com/call_back/update_call_back");
OapiCallBackUpdateCallBackRequest request = new OapiCallBackUpdateCallBackRequest();
request.setUrl("http://buyang001.vaiwan.com/eventreceive");
request.setAesKey("11111111lvdhntotr3x9qhlbytb18zyz5z111111111");
request.setToken("123456");
request.setCallBackTag(Arrays.asList("user_add_org", "user_modify_org"));
OapiCallBackUpdateCallBackResponse response = client.execute(request,accessToken);

返回结果

{
    "errcode": 0,
    "errmsg": "ok"
}
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容

删除事件回调接口

请求方式:GET(HTTPS)
请求地址https://oapi.dingtalk.com/call_back/delete_call_back?access_token=ACCESS_TOKEN
参数说明

参数 参数类型 必须 说明
access_token String 调用接口凭证

SDK请求示例(JAVA)

DingTalkClient  client = new DefaultDingTalkClient("https://oapi.dingtalk.com/call_back/delete_call_back");
OapiCallBackDeleteCallBackRequest request = new OapiCallBackDeleteCallBackRequest();
request.setHttpMethod("GET");
OapiCallBackDeleteCallBackResponse response = client.execute(request,accessToken);

返回结果

{
   "errcode": 0,
   "errmsg": "ok" 
}
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容

获取回调失败的结果

钉钉服务器给回调接口推送时,有可能因为各种原因推送失败(比如网络异常),此时钉钉将保留此次变更事件。用户可以通过此回调接口获取推送失败的变更事件。

请求方式:GET(HTTPS)
请求地址https://oapi.dingtalk.com/call_back/get_call_back_failed_result?access_token=ACCESS_TOKEN
参数说明

参数 参数类型 必须 说明
access_token String 调用接口凭证

SDK请求示例(JAVA)

DingTalkClient  client = new DefaultDingTalkClient("https://oapi.dingtalk.com/call_back/get_call_back_failed_result");
OapiCallBackGetCallBackFailedResultRequest request = new OapiCallBackGetCallBackFailedResultRequest();
request.setHttpMethod("GET");
OapiCallBackGetCallBackFailedResultResponse response = client.execute(request,accessToken);

返回结果

{
   "errcode": 0,
   "errmsg": "ok",
   "has_more": false,
   "failed_list": [
        {
            "user_add_org" : {
                "callbackData" : {},
                "corpid" : ""
            }
        },
        {
            "bpms_instance_change" : {
                "bpmsCallBackData" : {},
                "corpid" : ""
            }
        },
        {
            "bpms_task_change" : {
                "bpmsCallBackData" : {},
                "corpid" : ""
            }
        },
        {
            "label_conf_add" : {
                "roleLabelChange" : {},
                "corpid" : ""
            }
        }
   ]
 
}
参数 说明
errcode 返回码
errmsg 对返回码的文本描述内容
has_more 是否还有推送失败的变更事件,若为true,则表示还有未回调的事件
failed_list 事件列表,一次最多200个
user_add_org bpms_instance_change
corpid 回调失败数据所属corpid
bpmsCallBackData callbackData
以上内容是否对您有帮助:
在文档使用中是否遇到以下问题(多选):
  • 内容错误
  • 更新不及时
  • 链接错误
  • 缺少代码/图片示例
  • 太简单/步骤待完善
手机号
更多建议
提交成功,感谢您的反馈!