Webhook

If developer cannot connect to MQTT services, Webhook (custom callback URL) isn an alternative to connect and receive real-time data push.

The feature of Webhook is to transmit sensor data and event messages through HTTP POST command to designated URL (server) in real-time. For data security, please use HTTPS URL。

1. Server Configuration

Log into IoT cloud platform，access developer page - push message settings，fill in the developer Webhook address: the URL must support “Post” request because the data is requested through “Post” method.

In the website of the cloud platform, find advanced settings - developer, get your AppID, AppKey and AppSecret.

AppID as unique application identifier
AppKey as message encryption and decryption key
AppSecret message signature key

Developer can select message encryption and decryption modes:

Plain text mode
Safe mode

Mode selection and server configuration will take effect immediately, hence please make your selection and fill out the information with caution. Default encryption and decryption is in “plain text mode”; you are advised to configure the decryption code before selecting “safe mode” encryption.

2. Sensor Data Push

When end-device uploads data packet to the cloud, SENSORO server sends JSON data packet through “POST” request to developer's pre-filled Webhook address.

Standard device has only one sensor, therefore, pushed data packet contains only one type of sensor data. The following “POST” examples provide references of all types of sensor data.

Push request instructions

HTTP request mode: POST

https://YOUR_SERVER_URL

Sample parameters request

Request: {
    appId: '123456',
    sn: '0117C9XXXX',
    type: 'text', // Message type, text Common message
    deviceType: 'node',
    createdTime: '',
    msgId: '', //Message id
    data: { // Proclaimed writing
        battery: Int, 
        interval: Int,
        temperature: float,
        light: float,
        humidity: float,
        ch4:Int,
        pm2_5:Int,
        leak:Bool,
        smoke:Int,
        magnetic: { // Geomagnetic
            x: float,
            y: float,
            z: float
        },
        lonlat: [lon, lat],
        accelerometer: { //Accelerometer
            x: float,
            y: float,
            z: float
        },
        gyro: { // Gyroscope
            x: float,
            y: float,
            z: float
        },
        customer:  String// User defined sensor data
    },
    encryptData: '' // Encryption cipher security mode     
}

Parameter description

Parameter	YES/NO	Type	Sample value	Description
appId	√	String		Application unique identifier
sn	√	String		End-device identifier
type	√	String	text	Common message
deviceType	√	String	text	Device type
createdTime	√	Timestamp		Message timestamp
msgId	√	Number		Message Id
data	√	Object		Message content
interval	×	Number		Upload interval
battery	×	Number		battery
temperature	×	float		Temperature sensor data
light	×	float		Light sensor data
ch4	×	Number		CH4 sensor data
pm2_5	×	Number		PM2.5 sensor data
leak	×	Bool		Leak sensor data
smoke	×	Number		Smoke sensor data
magnetic	×	Object	{x: float, y: float, z: float}	data of terrestrial magnetism sensor
lonlat	×	Array	[lon, lat]	GPS longitude and latitude sensor data
accelerometer	×	Object	{x: float, y: float, z: float}	Triaxial accelerometer sensor data
gyro	×	Object	{x: float, y: float, z: float}	Gyroscope sensor data
customer	×	String	'customer string'	Customise sensor data

Return parameters

''

Parameter description

Parameter	YES/NO	Type	Sample value	Description
messages	×	String	'success'	Return paremeter，empty string is acceptable.

3. Task Event

When a task is assigned to modify “end-device” upload interval, there will be an event message when the task is completed.

Push request instructions

HTTP Request mode: POST

https://YOUR_SERVER_URL

Sample request parameters

Request: {
    appId: '123456',            
    taskId: 123,
    type: 'event', //event: Event message
    createdTime: Timestamp,
    msgId: '', //Message id
    data:{
        resultCode: 0, //0 Success，1，Fail
        resultData: {}   
    }
    encryptData: '' 
}

Parameter description

Parameter	YES/NO	Type	Sample value	Instruction
appId	√	String		Application unique identifier
taskId	√	String		Task Id
type	√	String	event	Event return message
createdTime	√	Timestamp		Message timestamp
msgId	√	Number		Message Id
resultCode	√	Number	0	Result, 0 Success, 1 Fail
resultData	×	Object		Task return message details

Example of return parameters

''

Parameter description

Parameter	Must of must not	Type	Sample value	Instruction
messages	×	String	'success'	Return parameter, allow empty return string

4. Response

When the developer's server receives the request, please respond with 2xx HTTP status code. If other HTTP status code is received, SENSORO will re-push three times and will not push again if these three attempts fail.

5. Verify if the message is from SENSORO

In order to verify the legitimacy, developer can verify the message body of the request and decrype the verified message body.

Message body signature is explained with details in “API authentication” - Message signature.

6. Push message encryption

When selecting safe mode, message encryption and decryption are both required when developer receives message and event notification (some events need to be responded, and this has to be encryped in advanced, too). However, of you call interfaces through API (modify configuration of end devices and transmit data to end devices), encryption is not required.

Message encryption is explained with details in “API authentication”- Message encryption.