更新时间:2023-04-07 GMT+08:00
分享

审批事件

配置事件订阅

钉钉会向应用推送订阅的事件,例如部门变更、签到通知、打卡通知等。通过订阅这些事件,可以更好地与钉钉集成。你只需告诉钉钉当某个事件发生时,钉钉需要推送消息到哪个URL,钉钉会以HTTP POST请求的方式将事件内容以JSON格式推送给你。

事件订阅流程

事件订阅的流程如下图所示。

首先,开发者需要在钉钉开放平台配置HTTP请求接收地址用于接收推送的订阅事件,然后设置要订阅的事件。在配置完请求地址后,钉钉开放平台会向该地址发送POST请求,只有在规定时间内正确返回了包含"success"的加密字符串才完成事件订阅。

配置请求地址和事件订阅

  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加密字符串。

消息加解密

为了保证数据传输的安全,钉钉在推送订阅事件时,会携带配置的token用来验证事件来源。同时使用该密钥对消息内容做对称加密。

单击这里获取回调加解密类库和对应demo。

钉钉服务器会把msg消息体明文编码成encrypt。encrypt = Base64_Encode(AES_Encrypt[random(16B) + msg_len(4B) + msg + $key])是对明文消息msg加密处理后的Base64编码。其中:

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

取出返回的JSON中的encrypt字段:

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

审批事件类型

事件类型

说明

bpms_task_change

审批任务开始、结束、转交。

注意

此事件仅针对当前审批人。

bpms_instance_change

审批实例开始、结束。

注意

此事件为审批流实例。

审批实例开始

示例:

{

"EventType": "bpms_instance_change",

"processInstanceId": "ad253df6-e175caf-xxxxxxxxxxxx",

"corpId": "corpidxxxxxxxxxxxxx",

"createTime": 1495592259000,

"title": "自测-1016",

"type": "start",

"staffId": "er5875",

"url": "https://aflow.dingtalk.com/dingtalk/mobile/homepage.htm",

"processCode":"Pro-xxx"

}

参数说明:

参数

说明

EventType

事件类型。

processInstanceId

审批实例id。

corpId

审批实例所在的企业corpId。

createTime

创建审批实例时间。时间戳,单位毫秒。

title

审批实例标题。

type

类型,type为start表示审批实例开始。

staffId

发起审批实例的员工userId。

url

审批实例url,可在钉钉内跳转到审批页面。

processCode

审批模板的唯一码。

审批实例结束|终止

示例:

{

"EventType": "bpms_instance_change",

"processInstanceId": "ad253df6-e175caf-xxxxxxxxxxxx",

"finishTime": 1495592305000,

"corpId": "dinge8a56572f80b02a8ffexxxx",

"title": "自测-1016",

"type": "finish",

"url": "https://aflow.dingtalk.com/dingtalk/mobile/homepage.htm?corpid=ding2c015874d817xxxx&dd_share=",

"result": "refuse",

"createTime": 1495592272000,

"staffId": "manager75",

"processCode":"Pro-xxx"

}

参数说明:

参数

说明

EventType

事件类型。

processInstanceId

审批实例id。

corpId

审批实例对应的企业corpId。

createTime

创建审批实例时间。时间戳,单位毫秒。

finishTime

结束审批实例时间。时间戳,单位毫秒。

title

实例标题。

type

  • finish:审批正常结束(同意或拒绝)
  • terminate:审批终止(发起人撤销审批单)

staffId

发起审批实例的员工userId。

url

审批实例url,可在钉钉内跳转到审批页面。

result

正常结束时result为agree,拒绝时result为refuse,审批终止时没这个值。

processCode

审批模板的唯一码。

审批任务开始

示例:

{

"EventType": "bpms_task_change",

"processInstanceId": "ce133dd0-5b22-9516-xxxxxxxxxxxx",

"corpId": "corpidxxxxxxxxxxxxx",

"createTime": 1495593189000,

"title": "自测-1016",

"type": "start",

"staffId": "manager75",

"processCode":"Pro-xxx"

}

参数说明:

参数

说明

EventType

事件类型。

processInstanceId

审批实例id。

corpId

发生审批任务变更的企业corpId。

createTime

创建任务的时间。时间戳,单位毫秒。

title

实例标题。

type

类型,type为start表示审批任务开始。

staffId

当前任务的审批人userId。

processCode

审批模板的唯一码。

审批任务结束

示例:

{

"EventType": "bpms_task_change",

"processInstanceId": "ce133dd0-5b22-9516-xxxxxxxxxxxx",

"finishTime": 1495605749000,

"corpId": "corpidxxxxxxxxxxxxx",

"title": "自测-1016",

"type": "finish",

"result": "refuse",

"remark": "拒绝理由",

"createTime": 1495593189000,

"staffId": "manager75",

"processCode":"Pro-xxx"

}

参数说明:

参数

说明

EventType

事件类型。

processInstanceId

审批实例id。

corpId

发生审批任务变更的企业corpId。

createTime

创建任务的时间。时间戳,单位毫秒。

finishTime

结束任务的时间。时间戳,单位毫秒。

title

实例标题。

type

审批任务结束类型:

  • finish:表示审批任务结束。
  • cancel:说明当前节点有多个审批人并且是或签,其中一个人执行了审批,其他审批人会推送cancel类型事件。

staffId

当前任务审批人的userId。

result

  • agree:同意
  • refuse:拒绝

remark

remark表示操作时写的评论内容。

processCode

审批模板的唯一码。

审批任务转交

示例:

{

"EventType": "bpms_task_change",

"processInstanceId": "439bda1c-d9-9d67-xxxxxxxxxxxx",

"finishTime": 1495542282000,

"corpId": "corpidxxxxxxxxxxxxx",

"title": "自测-2017",

"type": "finish",

"result": "redirect",

"createTime": 1495541847000,

"staffId": "08058646137",

"processCode":"Pro-xxx"

}

参数说明:

参数

说明

EventType

事件类型。

processInstanceId

审批实例id。

corpId

发生审批任务变更的企业corpId。

createTime

当前任务创建的时间。时间戳,单位毫秒。

finishTime

当前任务结束,即转交动作发生的时间戳,单位毫秒。

title

实例标题。

type

类型,type为finish表示审批任务转交。

staffId

操作转交动作的员工userId。

result

redirect:表示审批任务转交。

processCode

审批模板的唯一码。

相关文档