diff --git a/docs/How-to guides/How to create and use webhooks.md b/docs/How-to guides/How to create and use webhooks.md index f915dd2..45db46a 100644 --- a/docs/How-to guides/How to create and use webhooks.md +++ b/docs/How-to guides/How to create and use webhooks.md @@ -1,77 +1,75 @@ + --- sidebar_position: 6 -sidebar_label: How to create and use a webhook +sidebar_label: How to Create and Use a Webhook --- -# How to create and use webhooks + +# How to Create and Use Webhooks ## Introduction -Biotz provides webhook subscriptions for it's alarms. In short a [webhook](https://en.wikipedia.org/wiki/Webhook) is a method used by one application (e.g. Biotz) to send real-time data to another application (e.g. customers) when a specific event occurs. +Biotz provides webhook subscriptions for its alarms. In short, a webhook is a method used by one application (e.g., Biotz) to send real-time data to another application (e.g., customers) when a specific event occurs. ## Prerequisites -There is no Prerequisite to creating a webhook. However webhooks are used against device events, so to use them, you need a device type that includes at least one message type and schema. It's also recommended to have a device that has already transmitted some data. -## Creating a webhook +There are no prerequisites for creating a webhook. However, webhooks are used for device events, so to use them, you need a device type that includes at least one message type and schema. It's also recommended to have a device that has already transmitted some data. + +## Creating a Webhook -Webhooks are created from the “Developer tools” section in the sidebar. To create a webhook provide a name, and the mandatory "callback url" e.g. the URL that the event data is going to be pushed against. Webhooks only support https URLs +Webhooks are created from the "Developer Tools" section in the sidebar. To create a webhook, provide a name and the mandatory "callback URL" (i.e., the URL to which the event data will be pushed). Webhooks only support HTTPS URLs.
- ![Developer tools -> webhooks](img/developer_tools_webhooks.png) +![Developer Tools -> Webhooks](img/developer_tools_webhooks.png)
-Clicking “new webhook” gets you to a form, to enter the name and url for your webhook +Clicking "New Webhook" takes you to a form where you can enter the name and URL for your webhook. +
- ![New webhook](img/new_webhook.png) +![New Webhook](img/new_webhook.png)
- -On clicking "Save" the webhook is created, and a secret" is automatically generated. It is advised to regenerate the secrete regularly +Upon clicking "Save," the webhook is created, and a "secret" is automatically generated. It is advised to regenerate the secret regularly.
- ![Webhook created!](img/webhook_created.png) +![Webhook Created!](img/webhook_created.png)
-Now the webhook is ready for use. Don't forget to take a note of the webhook's name and secret for later use ! +Now the webhook is ready for use. Don't forget to take note of the webhook's name and secret for later use! +## Registering a Device Alarm with the Webhook -## Registering a device alarm with the webhook -A webhook to be useful must be subscribed to a Biotz event. For now only alarm notifications events support webhook integration. -To add one under the sidebar section Setup navigate to "Alarm Triggers" and choose a device type e.g. device type 1 +For a webhook to be useful, it must be subscribed to a Biotz event. Currently, only alarm notification events support webhook integration. To add one, navigate to "Alarm Triggers" under the "Setup" section in the sidebar and choose a device type (e.g., Device Type 1).
- ![Select device type from alarm triggers](img/alarm_trigger_webhook_1.png) +![Select Device Type from Alarm Triggers](img/alarm_trigger_webhook_1.png)
-Then either create or edit an alarm trigger and click under"Edit webhook list" +Then either create or edit an alarm trigger and click "Edit Webhook List."
- ![Edit wehook list](img/alarm_trigger_webhook_2.png) +![Edit Webhook List](img/alarm_trigger_webhook_2.png)
-Search your webhook by name and add it from the tropdown and then save. Now you can proceed to actually use the webhook from your app +Search for your webhook by name, add it from the dropdown, and then save. Now you can proceed to actually use the webhook from your app.
- ![Search and add webhook](img/alarm_trigger_webhook_3.png) +![Search and Add Webhook](img/alarm_trigger_webhook_3.png)
+## Receiving Webhook Event Data -## Receive webhook event data +If all the above steps were followed and there is at least one device that generates alarms, then alarm data will be sent to the webhook URI via POST. -If all the above steps were followed and there is at least one device that -generates alarms then alarm data will be send to the webhook uri via post. +From the client side, there should be validation of the webhook via the "Biotz-IoT-Signature" header entry. The Biotz-IoT-Signature has the following structure: -From the client side there should validation of the webhook via Biotz-IoT-Signature" header entry. Biotz-IoT-Signature has the following structure: -``` -Biotz-IoT-Signature:t=1492774577,v1=d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5, +Biotz-IoT-Signature: t=1492774577,v1=d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5, -``` -Where the string following v1= is the signed payload of the event and is created by first concatenating: +Where the string following `v1=` is the signed payload of the event and is created by first concatenating: * The string timestamp -* The character . -* The actual alarm payload in json, the body of the post request - -And then generating an SHA256 of the concatenation using the webhook secret key +* The character `.` +* The actual alarm payload in JSON (the body of the POST request) +And then generating an SHA256 hash of the concatenation using the webhook secret key.