YMCS webhook 简介 Webhook是一种基于HTTP的用户定义的回调API，您可以在您的基础设施中设置它，用于接收来自YMCS的变更通知和事件。要使用YMCS webhook, 用户需要在YMCS平台上填写可靠安全的HTTPS webhook URL并订阅感兴趣的事件。 webhook URL要求 要接收YMCS事件通知，用户需要提供可访问，HTTPS安全的URL，否则YMCS不会发通知到指定URL。 接收事件通知 当订阅的事件发生时，YMCS会发通知报文到预先配置的请求URL，客户应用服务器接收并响应处理。 通知报文的传输以HTTPS的方式，使用POST方法。报文格式限定为JSON格式。 报文格式 HTTPS 请求头部信息如下： Header 说明 content-type application/json content-length 请求体的内容长度(以字节为单位) authorization 订阅成功之后返回的验证 token，用于验证此请求是由 YIOT 系统发送 clientid 配置事件订阅的应用程序 ID x-yl-requestid 请求的链路跟踪id 请求 Body 格式示例如下： { "events": [ { "id": "6c29f04672b6492ebd0911c2da3414ac", "type": "alarm.created", "createTime": 1600063609555, "partyId": "b986e6eedd6245d697d79da86d6df57c", "data": { "id": "01d7ae1897f7418dad2d26609329be38", "event":"Offline", "level":1, "mac":"001565bbb1a9", "model":"SIP-T54S", "ip":"10.50.198.156", "site":"test" } } ] } event对象 字段名称 字段类型 说明 id String 事件数据唯一标识 type String 事件类型 createTime Long 业务服务生成事件时间 partyId String 企业ID userId String 用户ID data Object 事件数据，由业务决定格式和内容 重试策略 在收到YMCS发送的通知请求后，客户应用服务器需要在 5s 内返回 200 或 204 的响应，YMCS收到后就认为消息投递成功。 如果客户应用服务器在5s内没有响应该通知请求，YMCS将视此次通知失败，并根据策略重新发送通知请求。 具体重试策略为采用一定时间间隔重试，支持最大重试3次，具体间隔为：30s, 5m, 10m。 当重试周期结束还未投递成功，消息不会丢失，只是不再尝试投递，直到该订阅有新的消息到达，新消息到达时，会按照时间将3天内未投递的消息进行投递。 当重试过程中，应用服务器在 5s 内返回 200 或 204 的响应，YMCS就认为消息投递成功，不再重试。 由于网络原因或者事件处理慢，可能会出现收到重复事件的情况，建议客户应用服务器对事件进行幂等处理或者去重。 安全策略 YMCS通过HTTPS协议传输报文数据，防止数据被篡改。 应用服务器对于收到的请求要进行验证，获取请求头部的authorization信息，只有该信息和YMCS提供的订阅校验token一致时，才证明此请求是由YMCS发送的。 订阅校验token在YMCS事件订阅界面获取。 告警 生成告警 事件类型： alarm.created 事件说明: YMCS收到设备告警时，会触发该事件通知 事件数据 参数 数据类型 描述 id String 告警id event String 告警事件名称 mac String MAC model String 型号 示例 { "events": [ { "id": "6c29f04672b6492ebd0911c2da3414ac", "type": "alarm.created", "createTime": 1600063609555, "partyId": "b986e6eedd6245d697d79da86d6df57c", "data": { "id": "01d7ae1897f7418dad2d26609329be38", "event":"Offline", "mac":"001565bbb1a9", "model":"SIP-T54S" } } ] } 告警恢复 事件类型： alarm.recovered 事件说明: 当设备离线恢复在线, 设备的注册账号状态从失败变为成功时，会触发该事件通知 事件数据 参数 数据类型 描述 id String 告警id event String 告警事件名称 mac String MAC model String 型号 示例 { "events": [ { "id": "6c29f04672b6492ebd0911c2da3414ac", "type": "alarm.recovered", "createTime": 1600063609555, "partyId": "b986e6eedd6245d697d79da86d6df57c", "data": { "id": "01d7ae1897f7418dad2d26609329be38", "event":"Online", "mac":"001565bbb1a9", "model":"SIP-T54S", } } ] }