# 审批事件 配置事件订阅 钉钉会向应用推送订阅的事件，例如部门变更、签到通知、打卡通知等。通过订阅这些事件，可以更好地与钉钉集成。你只需告诉钉钉当某个事件发生时，钉钉需要推送消息到哪个URL，钉钉会以HTTP POST请求的方式将事件内容以JSON格式推送给你。 事件订阅流程 事件订阅的流程如下图所示。 首先，开发者需要在钉钉开放平台配置HTTP请求接收地址用于接收推送的订阅事件，然后设置要订阅的事件。在配置完请求地址后，钉钉开放平台会向该地址发送POST请求，只有在规定时间内正确返回了包含"**success**"的加密字符串才完成事件订阅。 ![](https://support.huaweicloud.com/bestpractice-sparkpack/zh-cn_image_0000002522793799.png) 配置请求地址和事件订阅 1. 登录[开发者后台](https://open-dev.dingtalk.com/)，找到已创建的企业内部应用。 2. 单击**事件订阅** ，然后单击编辑配置用于接收请求的HTTP地址。 **注意** 确保该地址公网可以访问。 ![](https://support.huaweicloud.com/bestpractice-sparkpack/zh-cn_image_0000002490434084.png) 编辑完请求地址，单击**保存**按钮时，开放平台会向你配置的网址推送一个 application/json 格式的 POST 请求, 用于验证你配置的网址的合法性。请求如下： { "encrypt": "ajls384kdjx98XX" // 加密字符串，解密方法请看下方的消息加解密 } 当你收到开放平台的POST验证请求时，你需要做解密处理，并在**1500ms** 内返回包含**success** 的加密字符串（**JSON格式**）。钉钉开放平台收到返回的JSON信息后会做解密处理，如果可以得到正常的success字符串，则验证回调信息推送正常，否则会判定为失败的回调信息。 3. 成功配置请求地址后，在**事件订阅** 列表区域，开启要订阅的事件。 ![](https://support.huaweicloud.com/bestpractice-sparkpack/zh-cn_image_0000002522633839.png) 接收并响应事件 - **接收事件信息** 当事件发生时，钉钉会主动向配置的HTTP地址发送POST请求，推送对应的事件信息。例如订阅通讯录事件后，当通讯录发生变更时，会向注册的HTTP地址推送事件信息，其格式如下。 **说明** 钉钉服务器推送信息是即时推送，如果企业的回调地址没有在1500毫秒内返回正确的加密信息给钉钉服务器，钉钉服务器会判断为推送失败。 请求的URL格式如下： http://你注册的HTTP地址?signature=111108bb8e6dbc2xxxx\×tamp=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用来验证事件来源。同时使用该密钥对消息内容做对称加密。 单击[这里](https://github.com/open-dingtalk/dingtalk-callback-Crypto)获取回调加解密类库和对应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 | 审批模板的唯一码。 |