webhook对接最佳实践
前提
云企业对应 open API功能已开通，未开通可联系对应区域销售或售前工程师。
启用事件订阅
- 企业拥有open API应用，可网页访问 https://developer.ylyun.com/manager/login
- 在我的应用中找到open API应用，并点击进入详情，打开事件订阅界面
-
将事件订阅开关打开，即可进行事件订阅的配置。事件订阅支持配置请求网址URL和所要订阅事件。
在请求网址URL输入框中输入URL，保存后，会校验该URL的可达性，避免设置无效的订阅地址。
- 请求网址URL用于接收并响应事件
- 当应用订阅的事件触发时，会向配置的请求网址URL发送对应的事件通知
支持的订阅事件定义见本文档同目录下各webhook定义文档。
接收事件通知
当订阅的事件发生时，Cloud会将通知报文发送到预先配置的各请求地址URL，应用服务器接收并进行响应处理。
通知报文的传输以HTTPS的方式，使用POST方法。报文格式限定为JSON格式。
报文格式
HTTPS 请求头部信息如下：
| Header | 说明 |
|---|---|
| content-type | application/json |
| content-length | 请求体的内容长度(以字节为单位) |
| authorization | 订阅成功之后返回的验证 token。此数据能够唯一标识一个订阅，用于验证此请求是由 YM 系统发送 |
| x-yl-requestid | 请求的链路跟踪id |
请求 Body 格式示例如下：
{
"events": [
{
"id": "6c29f04672b6492ebd0911c2da3414ac",
"type": "user.deleted",
"createTime": 1600063609555,
"partyId": "b986e6eedd6245d697d79da86d6df57c",
"userId": null,
"data": [
"3c2845f908a940a29a63a3ba9602a173"
]
}
]
}
event对象
| 字段名称 | 字段类型 | 说明 |
|---|---|---|
| id | String | 事件数据唯一标识 |
| type | String | 事件类型 |
| createTime | Long | 业务服务生成事件时间 |
| partyId | String | 企业ID |
| userId | String | 用户ID |
| data | Object | 事件数据，由业务决定格式和内容 |
重试策略
在收到Cloud发送的通知请求后，应用服务器需要在 5s 内返回 200 或 204 的响应，Cloud收到后就认为消息投递成功。 如果应用服务器在5s内没有响应该通知请求，Cloud将视此次通知失败，并根据策略重新发送通知请求。
具体重试策略为采用一定时间间隔重试，支持最大重试3次，具体间隔为：30s, 5m, 10m。 当重试周期结束还未投递成功，消息不会丢失，只是不再尝试投递，，直到该订阅有新的消息到达，新消息到达时，会按照时间将3天内未投递的消息进行投递。
- 当重试过程中，应用服务器在 5s 内返回 200 或 204 的响应，Cloud就认为消息投递成功，不再重试。
- 由于网络原因或者事件处理慢，可能会出现收到重复事件的情况，建议应用服务器对事件进行幂等处理或者去重。
安全策略
Cloud通过HTTPS协议传输报文数据，防止数据被篡改。
应用服务器对于收到的请求要进行验证，获取请求头部的authorization信息，只有该信息和Cloud提供的webhook订阅校验token一致时，才证明此请求是由Cloud发送。
webhook订阅校验token在如下事件订阅界面获取。
