事件对接说明（回调接口要求）

变更记录

1 介绍

开放事件订阅时，要求第三方系统提供一个可直接访问的Webhook回调接口，当事件触发时，系统会调用该接口向第三方系统传递事件消息。下面是平台对回调接口要求。

为保障数据传输安全，防止传输过程中数据被篡改和泄露，从V6.0.13版本开始，开放事件支持签名和加密。用户可以在事件订阅推送页面配置签名(页面必选，对接方也可不验签)和加密(可选)策略，操作详情见 事件推送订阅 ，平台在推送事件前会根据配置进行请求签名和数据加密。回调接口需要实现对应的验签和解密算法才能拿到事件数据。

事件触发时序图

2 回调接口协议

支持http/https协议。

3 请求说明

3.1 请求方式

POST+ application/json

3.2 请求参数

 请求头（Header)

请求体-加密报文

参数示例：

{"encrypt":"TgwQHnE78p83RiqIiuPSyMSjv89Aj0MBhvcd5Pq3mIXxpwF4YWOi/TARaDnAo0WkgATJwl5p13KznUKJJ25NDQylO3VebDsIXuN3hvS93qb2v6gkDuF9IaEDOUdOBxJhYJKcfX2o3wvAU84lfqH4F8yqLOGsSsljUvNKeWKpEPBgpn/+ZDS3v+K9Gi8cF0Ix5A/DMeBLkqO5sJQuuPb5ni5W7YLEfZrPMQh1r2BcaKqJ8wUrz6e8ZyfAGJ4s38OMIzEflHdX5FHjsQNJ4CgqsnUHAynE4nZRhBYrVLiVba3SBqqr+Fw8H3OaAuN0G5RijCyItrOUtG20z9UFEPF+LqGJ9XqroAGUJ0ijK0V9jTb0ExEibNxjCtYMGzthbMOo"}

注意：加密是对整个消息体做的加密。

请求体-不加密或解密报文

参数示例：

{
    "data":{
        "id":"1858013541517285376",
        "number":"eeee",
        "name":"eeee",
        "enable":"1",
        "status":"C",
        "remark":"",
        "creator":"1754371843654946816",
        "createtime":"2024-01-08 13:41:07.472",
        "modifytime":"2024-01-08 13:41:14.326",
        "modifier":"1754371843654946816"
    },
    "eventNumber":"kdtest.kemopenevt.osc.open.sortdelete",
    "msgId":"1858013636274991104",
    "entityNumber":"openapi_custom_sort",
    "operation":"save"
}

 4 验签说明

从V6.0.13版本后，所有开放事件推送必须进行请求签名，确保回调地址收到的请求来至于可信的源。用户可在事件订阅推送页面配置签名策略和签名密钥，签名策略支持HMAC_SHA_256和SHA_256两种。请根据页面配置的签名策略和密钥，使用对应的算法进行签名计算。

注意：V6.0.13版本后，开放事件推送时必须加签，所以订阅页面必须配置签名策略和密钥，对接方可选择验签或不验签，都不影响事件参数传递，但建议对接方做验签处理，避免传输过程中数据被篡改。

4.1 验签过程

1、从请求中获取如下参数

• timestamp：时间戳，获取请求头中的 x-kem-request-timestamp。

• nonce：数据数，获取请求头中的 x-kem-request-nonce。

• signature：消息签名，获取请求头中的  x-kem-signature。

• body：接收的请求体。

2、订阅推送页面设置的签名密钥 signsecretkey；

3、组装签名内容：signsecretkey + timestamp + nonce + body；

4、用订阅推送页面配置的签名算法对签名内容进行签名；

5、将签名结果转为16进制字符串，并与请求头中 x-kem-signature 签名内容进行比较是否一致。

4.2 Java示例代码

以 HMAC_SHA_256为例：

public String calculateSignature(String signsecretkey, String timestamp, String nonce, String bodyString) throws NoSuchAlgorithmException, InvalidKeyException {
   String content = signsecretkey + timestamp + nonce + bodyString;
   
   Mac hmacSHA256 = Mac.getInstance("HmacSHA256");
   SecretKe