{"metadata":{"image":[],"title":"","description":""},"api":{"url":"","auth":"required","settings":"","results":{"codes":[]},"params":[]},"next":{"description":"","pages":[]},"title":"Webhooks v2","type":"basic","slug":"webhooks-v2","excerpt":"","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```","updates":[],"order":11,"isReference":false,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"_id":"5a8f3586ef5caa0012cd83cc","project":"568bdc1483d2061900d86cdc","version":{"version":"0","version_clean":"0.0.0","codename":"","is_stable":true,"is_beta":true,"is_hidden":false,"is_deprecated":false,"categories":["59a7236e3fe4d90025117c10","59a72eb6cb0db3001b84cfe2","59a734eb757d030019b85af8","59c0243b1b2d07001a9d2b76","59c035e42126e10028effb12","59c06c40df5b3c0010584a13","59c1a5852cabe5002641a3e7","59c2fb00b2b45c0010b7a3d7","59c32ceb9aea850010ac4130","59c32e6e190c90003cb0d12f","59c33affb2b45c0010b7aa23","59c7dfa457bd8200105444dc","59c7e975c50cf30010d712a0","59cffdef0cd4dd0010294d54","59d0622ca91a810032c8f60c","59d06733c1aec60026253065","59d174d44ac471001a07b123","59d5a5e323e6e800103defb2","59ecf1d8ed507c001c52b255","59f76fef8581dc0010593e6f","5a0c003680a35b0012c35db0","5a8358722e78660075e45f42","5a846645b5ec3a001203517e","5b258091bc7a6700033b9cb5","5b26e48e024807000315a740","5b44edff3306680003663f5c","5b468abd3d4a9e0003789111","5b468d8f3dcb6a0003c6e374","5b47b0b93d4a9e000378a33a","5b538d114ea24f00033c726f","5b6a0efe402b32000336c33f","5bba5e5d7ba7710003bd902a","5bc2703349ac3a0013eec3e5","5c351061191e2b002b4988a8","5c8b01b199b56e00440aa018"],"_id":"59a72290d61777001b6c42c3","project":"568bdc1483d2061900d86cdc","createdAt":"2017-08-30T20:39:44.453Z","releaseDate":"2017-08-30T20:39:44.453Z","__v":35},"category":{"sync":{"isSync":false,"url":""},"pages":[],"title":"Platform Overview","slug":"platform-overview","order":2,"from_sync":false,"reference":false,"_id":"59cffdef0cd4dd0010294d54","project":"568bdc1483d2061900d86cdc","version":"59a72290d61777001b6c42c3","createdAt":"2017-09-30T20:26:23.487Z","__v":0},"user":"5a6a26281895510045b2cd40","createdAt":"2018-02-22T21:26:30.149Z","githubsync":"","__v":0,"parentDoc":null}