{"_id":"5a8f3586ef5caa0012cd83cc","project":"568bdc1483d2061900d86cdc","version":{"_id":"59a72290d61777001b6c42c3","project":"568bdc1483d2061900d86cdc","__v":23,"createdAt":"2017-08-30T20:39:44.453Z","releaseDate":"2017-08-30T20:39:44.453Z","categories":["59a7236e3fe4d90025117c10","59a72eb6cb0db3001b84cfe2","59a734eb757d030019b85af8","59c0243b1b2d07001a9d2b76","59c035e42126e10028effb12","59c06c40df5b3c0010584a13","59c1a5852cabe5002641a3e7","59c2fb00b2b45c0010b7a3d7","59c32ceb9aea850010ac4130","59c32e6e190c90003cb0d12f","59c33affb2b45c0010b7aa23","59c7dfa457bd8200105444dc","59c7e975c50cf30010d712a0","59cffdef0cd4dd0010294d54","59d0622ca91a810032c8f60c","59d06733c1aec60026253065","59d174d44ac471001a07b123","59d5a5e323e6e800103defb2","59ecf1d8ed507c001c52b255","59f76fef8581dc0010593e6f","5a0c003680a35b0012c35db0","5a8358722e78660075e45f42","5a846645b5ec3a001203517e"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"0.0.0","version":"0"},"category":{"_id":"59cffdef0cd4dd0010294d54","project":"568bdc1483d2061900d86cdc","version":"59a72290d61777001b6c42c3","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2017-09-30T20:26:23.487Z","from_sync":false,"order":2,"slug":"platform-overview","title":"Platform Overview"},"user":"5a6a26281895510045b2cd40","__v":0,"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2018-02-22T21:26:30.149Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":12,"body":"# Overview\n\nWebhooks 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. \n\nIn the future, webhooks will be available when metadata changes or new objects are created.\n\nDo not use webhooks for application updates, only for server updates.\n\nFilters may be applied that determine which types of events produce notifications.\n\nIt 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.\n\n# Secrets\n\nWebhook 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.\n\nProviding 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.\n\n#  Service Notifications\n\nService notifications are produced when a device's service properties are modified or its service methods are called.\n\nThe following event types spawn a webhook:\n* __Event__: Occurs when a device service event spawns.\n* __Get__: A device's service property is accessed.\n* __Set__: A device's service property is set.\n* __Call__: Occurs when a device's service method is called.\n* __Changed__: Occurs when a device's service property is changed.\n* __Info__: A device's information has been received.\n* __Error__: Occurs when a device encounters an error.\n\n“Get,” “Set,” and “Call” types all spawn from an explicit invocation. “Changed,” “Event”, and “Error” types occur automatically.\n\nThe events “Get”, “Set”, and “Call” will respond with a `transactionId`, as seen in the provided example.\n\n# Data Notifications\n\nData notifications are produced when a device itself is modified.\n\nThe following event types spawn a webhook:\n* __Created__: A device has been created.\n* __Updated__: A device's data has been updated.\n* __Deleted__: A device has been deleted.\n\n# Examples\n\n## Creating Webhook\n\n```\nPOST https://dev-ioe.droplit.io/api/webhooks HTTP/1.1\nauthorization: AUTH_TOKEN\ncontent-type: application/json\n{\n\t\"ecosystemId\": \"C5a5698aee57a960dbcda159e\",\n\t\"url\": \"https://webhook.site/a1abe761-c691-4fd5-80b6-34e8133b3600\",\n\t\"secret\": \"superSecret\",\n\t\"description\": \"very descriptive\"\n}\n```\n\n## Service Notifications\n\n### Initiating a Notification\n\nThe 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.\n```http\nPUT https://ioe.droplit.io/api/devices/D5122ec34e49f8c58041a2f21/services/BinarySwitch.switch HTTP/1.1\nauthorization: AUTH_TOKEN\ncontent-type: application/json\n{\n    \"value\": \"on\"\n}\n```\n\n### Response from the HTTP Request\n\n```json\n{\n    \"transactionId\": \"5a95b8ca3452851fd071fa06\"\n}\n```\n\n### Response from the Webhook\n\nThe notification that the property has been set:\n```json\n{\n  \"ecosystemId\": \"C5a5698aee57a960dbcda159e\",\n  \"environmentId\": \"Ef91b8eae678b6ba402ee9d21\",\n  \"items\": [\n    {\n      \"deviceId\": \"D5122ec34e49f8c58041a2f21\",\n      \"type\": \"set\",\n      \"service\": \"BinarySwitch\",\n      \"member\": \"switch\",\n      \"value\": \"on\"\n    }\n  ],\n  \"transactionId\": \"5a95b8ca3452851fd071fa06\",\n  \"callerType\": \"account\",\n  \"callerId\": \"5a5698aee57a960dbcda159e\"\n}\n```\n\nThe notification that the property has been changed:\n```json\n{\n  \"ecosystemId\": \"C5a5698aee57a960dbcda159e\",\n  \"environmentId\": \"Ef91b8eae678b6ba402ee9d21\",\n  \"items\": [\n    {\n      \"deviceId\": \"D5122ec34e49f8c58041a2f21\",\n      \"type\": \"changed\",\n      \"service\": \"BinarySwitch\",\n      \"index\": \"0\",\n      \"member\": \"switch\",\n      \"value\": \"on\"\n    }\n  ],\n  \"transactionId\": \"5a95b8ca3452851fd071fa08\"\n}\n```\n\n## Data Notifications\n\n### Initiating a Notification\n\nThe following request will create a device whose alias is \"webhookTest\". \n\n```http\nPOST https://ioe.droplit.io/api/devices/ HTTP/1.1\nauthorization: AUTH_TOKEN\ncontent-type: application/json\n{\n     \"environmentId\": \"Ef91b8eae678b6ba402ee9d21\",\n     \"alias\": \"webhookTest\"\n}\n```\n\n### Response from the HTTP Request\n\n```json\n{\n    \"id\": \"D5122ec34e49f8c58041a2f21\",\n    \"ecosystemId\": \"C5a5698aee57a960dbcda159e\",\n    \"environmentId\": \"Ef91b8eae678b6ba402ee9d21\",\n    \"type\": \"virtual\",\n    \"alias\": \"webhookTest2\",\n    \"meta\": {},\n    \"createdAt\": \"2018-03-27T18:29:53.428Z\"\n}\n```\n\n### Response from the Webhook\n\n```json\n{\n  \"type\": \"created\",\n  \"data\": {\n    \"ecosystemId\": \"C59eb8eae278b6bf402e39d25\",\n    \"environmentId\": \"E59eb8eae278b6bf402e39d26\",\n    \"type\": \"D\",\n    \"id\": \"D5aba8da1959ede31a41f45ed\"\n  }\n}\n```","excerpt":"","slug":"webhooks-v2","type":"basic","title":"Webhooks v2"}

Getting Started

Platform Overview

Data Modeling With Service Classes

Edge Server

Real Time Monitoring

REST API Usage

Tutorial

Account API

Clients API

Deleted API

Devices API

Ecosystems API

Environments API

Schemas API

Service Classes API

Users API

Webhooks API

Zones API

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. ```http 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 ```json { "transactionId": "5a95b8ca3452851fd071fa06" } ``` ### Response from the Webhook The notification that the property has been set: ```json { "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: ```json { "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". ```http 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 ```json { "id": "D5122ec34e49f8c58041a2f21", "ecosystemId": "C5a5698aee57a960dbcda159e", "environmentId": "Ef91b8eae678b6ba402ee9d21", "type": "virtual", "alias": "webhookTest2", "meta": {}, "createdAt": "2018-03-27T18:29:53.428Z" } ``` ### Response from the Webhook ```json { "type": "created", "data": { "ecosystemId": "C59eb8eae278b6bf402e39d25", "environmentId": "E59eb8eae278b6bf402e39d26", "type": "D", "id": "D5aba8da1959ede31a41f45ed" } } ```