钉钉开发文档

回调事件列表

更新时间: 2019-2-13

通讯录事件回调

当企业通讯录发生变化,并且注册回调事件时填写的事件类型“call_back_tag”包含通讯录事件,比如call_back_tag字段为“[“user_add_org”,“user_modify_org”]”,那么企业通讯录发生“通讯录用户增加”和“通讯录用户更改”,钉钉服务器会向回调url推送事件。

事件类型

  • 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 : 企业被解散
  • org_change : 企业信息发生变更
  • label_user_change :员工角色信息发生变更
  • label_conf_add:增加角色或者角色组
  • label_conf_del:删除角色或者角色组
  • label_conf_modify:修改角色或者角色组

POST数据解密后示例:

{
    "EventType": "user_add_org",
    "TimeStamp": 43535463645,
    "UserId": ["efefef" , "111111"],
    "CorpId": "corpid"
}

参数说明

参数 说明
EventType 事件类型
TimeStamp 时间戳
UserId 用户发生变更的userid列表
DeptId 部门发生变更的deptId列表
CorpId 发生通讯录变更的企业

返回说明

收到事件推送后,务必返回包含经过加密的字符串“success”的json数据,只有返回了对应的json数据,钉钉才会判断此事件推送成功。

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

群会话事件回调

当企业群会话发生变化,并且注册回调事件时填写的事件类型“call_back_tag”包含群会话事件,比如call_back_tag字段为“[“chat_add_member”,“chat_remove_member”]”,那么企业群会话发生了群会话添加人员和群会话删除人员,钉钉服务器会向url推送事件。

事件类型

  • chat_add_member :群会话添加人员
  • chat_remove_member :群会话删除人员
  • chat_quit:群会话用户主动退群
  • chat_update_owner :群会话更换群主
  • chat_update_title :群会话更换群名称
  • chat_disband :群会话解散群
  • chat_disband_microapp :绑定了微应用的群会话,在解散时回调

POST数据解密后示例:

{
    "EventType": "chat_add_member",
    "TimeStamp": 43535463645,
    "CorpId": "corpid",
    "ChatId": "chat90f29b737b56dc179df8w86t83d5f0f8",
    "UserId": ["efefef" , "111111"],
    "Operator": "manager0112",
}
参数 说明
EventType 事件类型
TimeStamp 时间戳
CorpId 发生群会话变更的企业
ChatId 会话的ID
UserId 用户发生变更的userid列表
Owner 已经更新的新的群主的userid
Title 已经更新的新的群标题
Operator 操作人员的userid
agentId 群会话绑定的微应用agentId

返回说明

收到事件推送后,务必返回包含经过加密的字符串“success”的json数据,只有返回了对应的json数据,钉钉才会判断此事件推送成功。

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

签到事件回调

用户签到事件发生,并且注册回调事件时填写的事件类型“call_back_tag”包含签到事件,比如call_back_tag字段为“[“check_in”]”,用户签到后,钉钉服务器会向url推送事件。

事件类型

  • check_in :  用户签到

POST数据解密后示例:

{
    "EventType": "check_in",
    "TimeStamp": 1495542282000,
    "CorpId": "ding2c015874d8175651",
    "StaffId": "08058646137"
  }
参数 说明
EventType 事件类型
TimeStamp 签到时间
CorpId 签到企业id
StaffId 签到用户id

审批事件回调

如果注册回调事件时包含审批事件“bpms_task_change”,“bpms_instance_change”,当审批事件发生后,钉钉服务器会向回调url推送事件。

事件类型

  • bpms_task_change :  审批任务开始,结束,转交
  • bpms_instance_change:审批实例开始,结束

审批实例开始

{
    "EventType": "bpms_instance_change",
    "processInstanceId": "ad253df6-e175caf-68085c60ba8a",
    "corpId": "ding2c4d8175651",
    "createTime": 1495592259000,
    "bizCategoryId": "bizCategoryId",
    "title": "自测-1016",
    "type": "start",
    "staffId": "er5875",
    "url": "https://aflow.dingtalk.com/dingtalk/mobile/homepage.htm"
  }
参数 说明
EventType 事件类型
processInstanceId 审批实例id
corpId 审批实例对应的企业
createTime 实例创建时间
bizCategoryId 审批实例对应表单类别
title 实例标题
type 类型 start
staffId 发起审批实例的员工
url 审批实例url,可在钉钉内跳转到审批页面

审批实例结束|终止

{
    "EventType": "bpms_instance_change",
    "processInstanceId": "ad253df6-e175caf-68085c60ba8a",
    "finishTime": 1495592305000,
    "corpId": "ding2c015874d8175651",
    "title": "自测-1016",
    "type": "finish",
    "url": "https://aflow.dingtalk.com/dingtalk/mobile/homepage.htm?corpid=ding2c015874d8175651&dd_share=",
    "result": "refuse",
    "createTime": 1495592272000,
    "bizCategoryId": "bizCategoryId",
    "staffId": "manager75"
  }
参数 说明
EventType 事件类型
processInstanceId ​审批实例id
corpId 审批实例对应的企业
createTime ​实例创建时间
finishTime 审批结束时间
bizCategoryId ​审批实例对应表单类别
title ​实例标题
type ​finish
staffId ​发起审批实例的员工
url ​审批实例url,可在钉钉内跳转到审批页面
result 正常结束时result为agree,终止时result为refuse

审批任务开始

{
    "EventType": "bpms_task_change",
    "processInstanceId": "ce133dd0-5b22-9516-925779977e9c",
    "corpId": "ding2c015874d8175651",
    "createTime": 1495593189000,
    "bizCategoryId": "bizCategoryId",
    "title": "自测-1016",
    "type": "start",
    "staffId": "manager75"
  }
参数 说明
EventType 事件类型
processInstanceId ​审批实例id
corpId 发生审批任务变更的企业
createTime ​实例创建时间
bizCategoryId ​审批实例对应表单类别
title ​实例标题
type ​类型 start
staffId ​​审批人id

审批任务结束

{
    "EventType": "bpms_task_change",
    "processInstanceId": "ce133dd0-5b22-9516-925779977e9c",
    "finishTime": 1495605749000,
    "corpId": "ding2c01651",
    "title": "自测-1016",
    "type": "finish",
    "result": "refuse",
    "remark": "拒绝理由",
    "createTime": 1495593189000,
    "bizCategoryId": "bizCategoryId",
    "staffId": "manager75"
  }
参数 说明
EventType 事件类型
processInstanceId ​审批实例id
corpId 发生审批任务变更的企业
createTime ​实例创建时间
finishTime ​审批结束时间
bizCategoryId ​审批实例对应表单类别
title ​实例标题
type ​finish
staffId ​​审批人id
result 同意时result为agree,拒绝时result为refuse
remark remark表示操作时写的评论内容

审批任务转交

{
    "EventType": "bpms_task_change",
    "processInstanceId": "439bda1c-d9-9d67-8081ede79716",
    "finishTime": 1495542282000,
    "corpId": "ding2c015874d8175651",
    "title": "自测-2017",
    "type": "finish",
    "result": "redirect",
    "createTime": 1495541847000,
    "bizCategoryId": "bizCategoryId",
    "staffId": "08058646137"
  }
参数 说明
EventType 事件类型
processInstanceId ​审批实例id
corpId 发生审批任务变更的企业
createTime ​实例创建时间
finishTime ​审批结束时间
bizCategoryId ​审批实例对应表单类别
title ​实例标题
type ​finish
staffId ​审批人id
result redirect
以上内容是否对您有帮助:
在文档使用中是否遇到以下问题(多选):
  • 内容错误
  • 更新不及时
  • 链接错误
  • 缺少代码/图片示例
  • 太简单/步骤待完善
手机号
更多建议
提交成功,感谢您的反馈!