Create and manage webhooks

A webhook is a way to send a notification via HTTP to another application when an event occurs. You can use Kobiton webhooks to notify your app or an internal system when certain events occur in Kobiton. For example, you might use webhooks to alert your remote application when a device has gone offline or becomes available instead of periodically polling Kobiton via REST APIs to determine whether changes have occurred.

Webhooks can be set up by org admins or any role with the org_setting.modify permission enabled.

Supported webhook events

A webhook is triggered to send an HTTP callback when a particular event occurs.

Kobiton currently supports creating device status webhooks for the following events:

  1. Online: from any status, except utilizing, to online
  2. Offline: from any status to offline
  3. Utilizing: from any status to utilizing
  4. Unplugged: from any status to unplugged

Note: Device status webhooks are only available for Private and Local devices. They cannot be used to report status for Public devices.

Create a webhook

In the Kobiton Portal, select your name from the main menu and choose Settings from the options.

Screen_Shot_2023-01-06_at_11.16.10_AM.png

 

Select the Webhook Settings tab.

Screen_Shot_2023-01-06_at_11.14.42_AM.png

 

Select Create Webhook.

Screen_Shot_2023-01-06_at_11.18.04_AM.png

Complete the required information as described below:

Parameter Required Format Description
Webhook Name Yes case-sensitive, 50 characters maximum Name of the webhook; it must be unique to the org
Example: Webhook for online status
URL Yes 512 characters maximum, valid URL syntax The URL where the callback should be sent
Description No 512 characters maximum Description of the webhook
Event Yes (at least 1 event enabled) On/off toggle The type of event to trigger the callback
 
Screen_Shot_2023-01-06_at_11.30.37_AM_copy.png

Choose one or more event triggers by enabling the toggle of each event. Then, select Save.

Screen_Shot_2023-01-06_at_11.30.37_AM_copy_2.png
 

Execute a webhook

When a webhook is created, it tracks the status of the Private and Local devices in an org. It sends HTTP callbacks to the specified URL when a condition is met for those devices.

The body of the callback will be similar to the below:

{
  "creationTime": "2023-01-06T04:52:36.963Z",
  "eventType": "DEVICE",
  "eventActivity": "device.state.utilizing",
  "eventDescription": "Utilizing",
  "deviceUdid": "ce0917198075440c057e",
  "deviceName": "Galaxy Note 8",
  "orgId": 2,
  "webhookId": 129,
  "webhookName": "Webhook for All events"
}

See below for details of the parameters in the example above:

Parameter Description
creationTime The date and time the callback is sent
eventType The type of event
eventActivity The triggering event
For offline and online events, it appears with the format: device.status.<event>
For unplugged and utilizing events, it appears with the format: device.state.<event>
eventDescription The description of the webhook triggering event
deviceUdid The UDID of the device
deviceName The name of the device
orgId The unique ID of the organization
webhookId The unique ID of the webhook
webhookName The webhook name

Delete a webhook

If you no longer want to receive a callback, delete the webhook.

Navigate to Webhook Settings, select a webhook, and choose Delete.

Screen_Shot_2023-01-06_at_12.11.54_PM.png

Confirm the deletion of the webhook by selecting Delete again in the modal:

Screen_Shot_2023-01-06_at_12.13.07_PM.png
 

Edit a webhook

Go to Webhook Settings, select a webhook and choose Edit.

Screen_Shot_2023-01-06_at_12.14.01_PM.png

Make changes and select Save.

Screen_Shot_2023-01-06_at_12.15.27_PM.png
 

Limitations

  • Authentication to URLs for webhook callbacks is currently not supported.
  • It is not possible to limit the scope of devices tracked by webhook to specific teams or device bundles.

 

Was this article helpful?
0 out of 0 found this helpful