Droplit.io Portal
API Reference

Webhooks v2

Overview

Webhooks provide real-time callbacks to the server when device events happen in an ecosystem. They are also directly associated with the ecosystem they monitor. Webhooks can be configured through the developer portal or fully managed from the API. Unless events occur simultaneously, each event will create its own separate webhook.

In the future, webhooks will be available when metadata changes or new objects are created.

Do not use webhooks for application updates, only for server updates.

Filters may be applied that determine which types of events produce notifications.

It is possible that several notifications will be captured by the webhook simultaneously. In the case of such an event, each notification will have its own entry in the "items" array of each transaction.

Secrets

Webhook endpoints are open to the internet to be called from anywhere. In order to verify that a call has come from the Droplit.io servers, use a secret key.

Providing a secret key in the webhook configuration will add an SHA-256 HMAC hexdigest to webhook calls in an x-droplit-signature HTTP request header. The receiving application may then compare this signature with its own SHA-256 HMAC digest generated from the same secret to ensure the webhook call originated from the Droplit.io servers.

Service Notifications

Service notifications are produced when a device's service properties are modified or its service methods are called.

The following event types spawn a webhook:

  • Event: Occurs when a device service event spawns.
  • Get: A device's service property is accessed.
  • Set: A device's service property is set.
  • Call: Occurs when a device's service method is called.
  • Changed: Occurs when a device's service property is changed.
  • Info: A device's information has been received.
  • Error: Occurs when a device encounters an error.

“Get,” “Set,” and “Call” types all spawn from an explicit invocation. “Changed,” “Event”, and “Error” types occur automatically.

The events “Get”, “Set”, and “Call” will respond with a transactionId, as seen in the provided example.

Data Notifications

Data notifications are produced when a device itself is modified.

The following event types spawn a webhook:

  • Created: A device has been created.
  • Updated: A device's data has been updated.
  • Deleted: A device has been deleted.

Examples

Creating Webhook

POST https://dev-ioe.droplit.io/api/webhooks HTTP/1.1
authorization: AUTH_TOKEN
content-type: application/json
{
	"ecosystemId": "C5a5698aee57a960dbcda159e",
	"url": "https://webhook.site/a1abe761-c691-4fd5-80b6-34e8133b3600",
	"secret": "superSecret",
	"description": "very descriptive"
}

Service Notifications

Initiating a Notification

The following request will set the BinarySwitch.switch property of the device with ID D5122ec34e49f8c58041a2f21 to on. This alteration will be picked up and displayed by the created webhook.

PUT https://ioe.droplit.io/api/devices/D5122ec34e49f8c58041a2f21/services/BinarySwitch.switch HTTP/1.1
authorization: AUTH_TOKEN
content-type: application/json
{
    "value": "on"
}

Response from the HTTP Request

{
    "transactionId": "5a95b8ca3452851fd071fa06"
}

Response from the Webhook

The notification that the property has been set:

{
  "ecosystemId": "C5a5698aee57a960dbcda159e",
  "environmentId": "Ef91b8eae678b6ba402ee9d21",
  "items": [
    {
      "deviceId": "D5122ec34e49f8c58041a2f21",
      "type": "set",
      "service": "BinarySwitch",
      "member": "switch",
      "value": "on"
    }
  ],
  "transactionId": "5a95b8ca3452851fd071fa06",
  "callerType": "account",
  "callerId": "5a5698aee57a960dbcda159e"
}

The notification that the property has been changed:

{
  "ecosystemId": "C5a5698aee57a960dbcda159e",
  "environmentId": "Ef91b8eae678b6ba402ee9d21",
  "items": [
    {
      "deviceId": "D5122ec34e49f8c58041a2f21",
      "type": "changed",
      "service": "BinarySwitch",
      "index": "0",
      "member": "switch",
      "value": "on"
    }
  ],
  "transactionId": "5a95b8ca3452851fd071fa08"
}

Data Notifications

Initiating a Notification

The following request will create a device whose alias is "webhookTest". 

POST https://ioe.droplit.io/api/devices/ HTTP/1.1
authorization: AUTH_TOKEN
content-type: application/json
{
     "environmentId": "Ef91b8eae678b6ba402ee9d21",
     "alias": "webhookTest"
}

Response from the HTTP Request

{
    "id": "D5122ec34e49f8c58041a2f21",
    "ecosystemId": "C5a5698aee57a960dbcda159e",
    "environmentId": "Ef91b8eae678b6ba402ee9d21",
    "type": "virtual",
    "alias": "webhookTest2",
    "meta": {},
    "createdAt": "2018-03-27T18:29:53.428Z"
}

Response from the Webhook

{
  "type": "created",
  "data": {
    "ecosystemId": "C59eb8eae278b6bf402e39d25",
    "environmentId": "E59eb8eae278b6bf402e39d26",
    "type": "D",
    "id": "D5aba8da1959ede31a41f45ed"
  }
}