Webhook

如果开发者不能对接 MQTT 服务，可以使用 Webhook 推送的方式接收实时数据的推送。Webhook 的功能是将传感器数据和事件消息通过 HTTP POST 命令实时发送到指定的 URL(服务器)，为保护您的数据安全，请使用 HTTPS URL。

SENSORO 服务器在 5 秒内收不到响应会断掉连接，并且重新发起请求，总共重试三次。假如服务器无法保证在五秒内处理并回复，可以直接回复空字符串，SENSORO 服务器不会对此作任何处理，并且不会发起重试。

一、填写服务器配置

登陆 IoT 云平台官网后，在平台官网的 开发者- 消息推送设置，填写开发者 Webhook 地址, 其中 URL 必须支持 POST 请求方法，因为数据是通过 POST 的方式推送。

在平台官网 高级功能 - 开发者, 得到对应的 AppID, AppKey 和 AppSecret。

• AppID 作为应用唯一标示符
• AppKey 作为消息加密解密秘钥
• AppSecret 作为消息签名密钥

同时，开发者可选择消息加解密方式:

• 明文模式
• 安全模式

模式的选择与服务器配置在提交后都会立即生效，开发者谨慎填写及选择。加解密方式的默认状态为明文模式，选择安全模式需要提前配置好相关加解密代码。

注： 推送数据包括三种内容： 传感器上报的实时数据、传感器状态改变相关数据、传感器下行任务的结果

二、传感器数据推送(传感器上报的实时数据)

当 终端 向云平台上传数据包时，SENSORO 服务器将 JSON 数据包 POST 请求到开发者填写的 Webhook 地址。

标准设备上只有一个传感器,所以推送的数据包中只有一种传感器数据，以下请求示例枚举所有传感器类型的数据.

注意:

1. α 开发者套件或者 α 传输模块推送的传感器数据只有 `customer` 字段, 需要对 customer 做数据解析。
2. α 开发者套件默认解析规则如下:
    第 0 个字节: 前缀，解析时跳过
    第 1~4 个字节: 温度数据，float型小端模式
    第 5~8 个字节: 湿度数据，float型小端模式
    第 9~12 个字节: 光线数据，float型小端模式

请求参数举例

Request: {
    appId: '123456789ABC',
    sn: '0117C9XXXX',
    type: 'text', // 消息类型, text 普通消息
    deviceType: 'node',
    createdTime: '',
    msgId: '', //消息 id
    band: 'SE433', // 频段
    rssi: -50, // 信号强度
    snr: 11.5, // 信噪比
    data: { // 明文
        battery: Int, //电池电量
        temperature: float,
        light: float,
        humidity: float
    },
    encryptData: '' // 安全模式开启后的加密密文
}

参数说明

• 所有设备类型必有字段

注： 以下各表中 . 表明包含层级。

• 1.设备类型: α 芯片 和 α 模块， 特有字段及deviceType取值说明

• 2.设备类型: α 传感器， 特有字段及deviceType取值说明

• 3.设备类型: α 一氧化碳 参数说明

• 4.设备类型: α 二氧化碳， 特有字段及deviceType取值说明

• 5.设备类型: α 二氧化氮， 特有字段及deviceType取值说明

• 6.设备类型: α 二氧化硫， 特有字段及deviceType取值说明

• 7.设备类型: α 天然气， 特有字段及deviceType取值说明

• 8.设备类型: α 臭氧， 特有字段及deviceType取值说明

• 9.设备类型: α 氨气， 特有字段及deviceType取值说明

• 10.设备类型: α TVOC， 特有字段及deviceType取值说明

• 11.设备类型: α PM， 特有字段及deviceType取值说明

• 12.设备类型: α 液化石油气， 特有字段及deviceType取值说明

• 13.设备类型: α 烟雾， 特有字段及deviceType取值说明

• 14.设备类型: α 倾角， 特有字段及deviceType取值说明

• 15.设备类型: α 温湿度， 特有字段及deviceType取值说明

• 16.设备类型: α 跑冒滴漏， 特有字段及deviceType取值说明

• 17.设备类型: α 灯井， 特有字段及deviceType取值说明

• 18.设备类型: α 温湿光， 特有字段及deviceType取值说明

• 19.设备类型: α 追踪器， 特有字段及deviceType取值说明

返回参数说明

三、任务事件推送(传感器下行任务的结果)

任务下发修改 终端 上传数据周期时，任务完成时的事件推送。

请求参数举例

Request: {
    appId: '123456789ABC',
    sn: '0117C9XXXX',
    taskId: 123,
    type: 'event', //event: 事件消息
    createdTime: timestamp,
    msgId: '', //消息 id
    resultCode: 0, //0 成功，1，失败
    resultData: {}
}

参数说明

返回参数说明

四、传感器状态改变相关数据推送

根据设备何时上报数据及上报数据的内容，使得设备具有多种状态，当设备状态改变时，推送此种消息。

请求参数举例

Request: {
    appId: '123456789ABC',
    sn: '0117C9XXXX',
    type: 'statusChanged',
    createdTime: timestamp,
    msgId: '', //消息 id
    band: 'SE433',
    snType: 'device',
    normalStatus: 0
}

参数说明

normalStatus 取值及含义：

返回参数说明

五、接收响应

当开发者服务器接收到请求后，请响应 2xx 的 HTTP 状态码。如果接收到其他 HTTP 状态码，SENSORO 会尝试重新推送 3 次，失败 3 次后将不再推送此条数据。

六、验证消息是否来自 SENSORO

为了验证消息体的合法性，开发者可用以验证消息体是来自 SENSORO 请求真实性，并对验证通过的消息体进行解密。

消息签名具体在 API权限检验 - 消息体签名。

七 、推送消息加密

选择安全模式，开发者在接收消息需要进行消息加解密， 接收事件不需要加密。通过 API 主动调用接口(修改终端配置和下行终端数据)时，不需要进行加密。

消息加密具体在 API权限校验- 消息体加密。