Skip to main content

WebHooks

Working#

To integrate kelvin events with your own application, you need to have public and private keys which are required for signing and verifying data. These keys can be generated from the kelvin portal. You need to be an administrator or a super user in order to create these keys. (For more information on Roles check out this [link]). You can find the keys in Integrations section of myaccount on kelvin portal.

Creating a Web Hook.#

  1. Login to the kelvin portal.
  2. Click on the profile icon for a drop down to show up.

Integrations

  1. Select Company Profile from the dropdown.
  2. Click on the Integrations Tab in the Company Profile section
  3. Now Click on Create Integration button, once clicked a dialog box would show up.

Web hook

  1. Give a application id to your webhook.
  2. Now select webhook from the integration type dropdown which contains "API Key" and "Web Hook" as options.
  3. Now select the version of the webhook, it should be v2.0.
  4. Also, give the Application URL (if any) of your application to which data should be sent.
  5. Now click on Save and a CSV file is downloaded with public, private keys. These keys can be used for verifying the request source..

Data Format.#

For version v1.0, request body is sent in JSON format. Following is the typical data format.

{
"timestamp":
"signature":
"payload":{
"type":
"operation":
"data":{},
},
}

Device Ping Request Body Format:

{
"timestamp":
"signature":
"payload":{
"type":
"operation":
"data":{
"imei":
"interval":{
"collection":
"transmit":
},
"network":{
"sim": {
"rssi":
}
},
"timestamp":
"battery":
"battery_voltage":
"location": [
{
"hits": ,
"q": {
"waps": [
{
"macAddress":
},
{
"macAddress":
},
{
"macAddress":
}
],
"cts": [
{
"mnc":
"mcc":
"radioType":
"lac":
"cid":
}
]
},
"lng":
"accuracy":
"queriedAt":
"source":
"cachedAt":
"lat":
}
],
"temperature":
"light":
"acceleration":
},
},
}

Device Ping Request Body Example:

{
"timestamp": 1610308993220,
"signature": "ashfoeihs#29402",
"payload": {
"type": "devicePing",
"operation": "create",
"data": {
"imei": "30124123",
"interval": {
"collection": 1,
"transmit": 15
},
"network": {
"sim": {
"rssi": 12,
}
},
"timestamp": 1610308993220,
"battery": 92.34,
"battery_voltage": 3121,
"location": [
{
"hits": 1,
"q": {
"waps": [
{
"macAddress": "6c:31:0e:4b:1d:83"
},
{
"macAddress": "3c:51:0e:38:a4:c3"
},
{
"macAddress": "3c:51:0e:38:a4:c2"
}
],
"cts": [
{
"mnc": 1,
"mcc": 505,
"radioType": "lte",
"lac": 36871,
"cid": 17676
}
]
},
"lng": 116.0123039,
"accuracy": 60,
"queriedAt": 1644409702,
"source": "MIX",
"cachedAt": 1644409702,
"lat": -31.9238247
}
],
"temperature": [20.55, 21, 25, 27, 21.7, 20, 23.1],
"light": [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
"acceleration": [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
}
}
}

If you select v2.0 for the webhooks then the request body is in the following format.

{
"type":
"operation":
"data":{},
}

The timestamp and signature are to be sent in headers, as shown below.

headers:{
"X-Kelvin-Webhook-Signature":signature,
"X-Kelvin-Webhook-Timestamp":timestamp,
}

Device Ping Request Body Format:

{
"type":
"operation":
"data":{
"imei":
"interval":{
"collection":
"transmit":
},
"network":{
"sim": {
"rssi":
}
},
"timestamp":
"battery":
"battery_voltage":
"location": [
{
"hits": ,
"q": {
"waps": [
{
"macAddress":
},
{
"macAddress":
},
{
"macAddress":
}
],
"cts": [
{
"mnc":
"mcc":
"radioType":
"lac":
"cid":
}
]
},
"lng":
"accuracy":
"queriedAt":
"source":
"cachedAt":
"lat":
}
],
"temperature":
"light":
"acceleration":
},
}

Device Ping Request Body Example:

{
"type": "devicePing",
"operation": "create",
"data": {
"imei": "30124123",
"interval": {
"collection": 1,
"transmit": 15
},
"network": {
"sim": {
"rssi": 12,
}
},
"timestamp": 1610308993220,
"battery": 92.34,
"battery_voltage": 3121,
"location": [
{
"hits": 1,
"q": {
"waps": [
{
"macAddress": "6c:31:0e:4b:1d:83"
},
{
"macAddress": "3c:51:0e:38:a4:c3"
},
{
"macAddress": "3c:51:0e:38:a4:c2"
}
],
"cts": [
{
"mnc": 1,
"mcc": 505,
"radioType": "lte",
"lac": 36871,
"cid": 17676
}
]
},
"lng": 116.0123039,
"accuracy": 60,
"queriedAt": 1644409702,
"source": "MIX",
"cachedAt": 1644409702,
"lat": -31.9238247
}
],
"temperature": [20.55, 21, 25, 27, 21.7, 20, 23.1],
"light": [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
"acceleration": [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
}
}

Verfiying the request source.#

Once the webhooks public and private keys are successfully generated, request body will be posted to the endpoint URL that is saved. From your end, once the request is received, it can be checked for the authentic source using the public key generated in the ‘Create Integration step’. Kelvin uses Elliptic Curve Digital Signature Algorithm for digitally signing the payload. Specifically, we use the starkbank-ecdsa library. You can use the same library (has implementations in Go, Java) to verify the data source. You can find the libraries at https://github.com/starkbank
Request verification example can be found at https://www.npmjs.com/package/starkbank-ecdsa