Webhooks provide a seamless integration to notify third-party systems of Kio App alert events in real-time. A Webhook sends an alert payload directly to a designated URL, enabling third-party systems to process and receive alert events triggered within a Kio App.
Topics include:
-
You must be assigned to the Company Settings User or Administrator role.
-
To assign Webhooks to Alert Rules within the Kio Apps, you must be assigned to the Kio App's Administrator role.
-
A Webhook payload can include both built-in alert event variables and custom variables.
-
The system stores and logs each Webhook event, both within the Company Settings and in the alerts activated within the Kio Apps.
-
Be sure to follow our best practices and advice, including:
Reliability: Implement error handling and retry logic to manage payload reception failures.
Security: Secure Webhook endpoints using HTTPS and validate incoming data.
Efficiency: Include only essential data in the payload to minimize processing time and bandwidth usage.
Kio Apps activate alerts based on specific conditions set within Alert Rules. These alerts can be sent to third-party systems through Webhooks, allowing a streamlined integration method for communication and response mechanisms.
-
Staff Safe Emergency Call: Alerts can be activated from Smart Badge button press event (staff duress alerts).
-
Asset Tracker: Alerts can be activated when assets enter or exit a room (location-based events).
-
IV Pump or Wheelchair Manager: Alerts can be activated from a Asset Tag button click (button events), when room PAR level theresholds are met, or when pumps or wheelchairs enter or exit a room (location-based events)
-
Device Health: Alerts can be activated for device low battery levels or an offline statuses.
-
Slack notifications: Send alerts directly to a Slack channel.
-
ServiceNow: Automate the creation of incidents for alerts.
-
Emergency Notification Systems: Integrate with leading platforms, such as Singlewire and Spok, to streamline and automate emergency notifications.
-
Nurse Call Cancellation Systems: Integrate with systems, such as Rauland Borg and Hillrom, to allow staff to cancel alerts quickly and efficiently.
-
EHRs: Connect with your existing EHR systems to ensure a comprehensive, integrated approach to staff and patient safety.
The following provides the details of the settings within a Webhook.
Setting |
Description |
---|---|
Name |
A unique name that identifies the Webhook. |
URL |
The endpoint URL of the third-party system that receives the alert payload. A webhook sends requests to the URL using the POST HTTP method. |
Header |
A Webhook includes a header in each alert event. The header contains metadata necessary for processing the alerts, such as authentication or content types. See an example.
|
URL Parameters |
URL parameters are part of the query string appended to the URL after the ? character. They are often used for information that is context-specific or directly tied to the URL resource. Any required authentication or identification paramaters should be included directly within the URL as query parameters. Example: Click image to enlarge |
Apps |
Sets the Kio Apps the Webhook can be assigned to within the app's Alert Rules. A Webhook can be assigned to one or multiple apps. When a Webhook is assigned to an Kio App Alert Rule, the Webhook invokes HTTP POST request to the URL when an alert it triggered by the rule. |
Payload (body) |
Body of the HTTP POST request containing the alert event data. Payloads can be formatted as JSON, XML, or Text. View an example.
From the payload field, enter a$ character to view and select the variables to include. |
A Webhook payload is the body HTTP POST request containing the alert event data.
The following provides the alert event variables that can be included in a payload.
Variable/Parameter |
Type |
Description |
---|---|---|
$_alertBuilding |
string |
Name of the building where the alert occurred; user-defined in Kio Cloud Smart Location |
$_alertBuildingId |
number |
Unique identifier of the building; system-defined value |
$_alertCampus |
string |
Name of the campus where the alert occurred; user-defined in Kio Cloud Smart Location |
$_alertCampusId |
number |
Unique identifier of the campus; system-defined value |
$_alertCreatedDate |
string |
Date and time (ISO 8601 Timestamp) of alert activation Example: 2024-03-26T02:51:12.572961223Z |
$_alertDeviceMac |
string |
MAC address of the Kontakt.io Tag device assigned to the entity |
$_alertFloor |
string |
Name of the floor where the alert occurred; user-defined in Kio Cloud Smart Location |
$_alertFloorId |
number |
Unique identifier of the floor; system-defined value |
$_alertName |
string |
Name of the alert; user-defined value in the Kio App Alert Rule |
$_alertUUID |
integer |
Unique identifier for the alert; system-generated value |
$_alertResponseUrl |
string |
URL that will open a web page showing the alert details and ack and resolve buttons |
$_alertRoom |
string |
Name of the room where the alert occurred; user-defined value Kio Cloud Smart Location |
$_alertRoomId |
integer |
Unique identifier for the room; system-defined value |
$_alertRuleName |
string |
Name of the Alert Rule; user-defined value configured in the Kio App Alert Rule |
$_alertTriggeredBy |
integer |
Unique ID of the entity that triggered the alert; user-defined value |
$_alertTriggeredByCondition |
string |
Value of the condition reached that activated the alert event; user-defined in the Kio App Alert Rule |
$_alertType |
string |
Type of the alert; user-defined in the Kio App Alert Rule |
$_alertUUID |
string |
Unique alert identifier; system-generated value |
$_alertUrgency |
string |
Alert Severity level; configured in the Kio App Alert Rule One of: critical, high, medium, low, info |
$_alertDeviceName |
string |
Name of the Kontakt.io Tag device; user-defined in Device Management 2.0 |
{"text":"Webhook automated testing: Alert: $_alertUUID, ($_alertType) - $_alertName Created at: $_alertCreatedDate Location: Campus: $_alertCampus (id: $_alertCampusId) Building: $_alertBuilding (id: $_alertBuildingId) Floor: $_alertFloor (id: $_alertFloorId) Room: $_alertRoomId Triggered: By: $_alertTriggeredBy Condition: $_alertTriggeredByCondition Alert Rule: $_alertRuleName Urgency: $_alertUrgency Custom info: $testCustomVariable"}
A custom variable can be included in a Webhooks payload. Custom variables are provided in the "Customed" list within the payload's list of available variables.
To send Kio alerts to a third-party system, the Webhook must be assigned to an Alert Rule. If you need to create a new Alert Rule, from the relevant Kio App, go to its Settings menu > select Alert Rules > Create Alert Rule.
-
From your Kontakt.io Launchpad, open the relevant Kio App.
-
From the Settings menu, select Alert Rules.
-
From the list, select the Name of the Alert Rule > select Edit.
-
Navigate to the Actions section > select the Webhook option > select the Webhook to be assigned.
-
Select Save.
-
Activate an alert.
Staff Safe alert: activated from a Kontakt.io Smart Badge - staff assigned to the badge must be included in the Alert Rule with the assigned Webhook.
-
Confirm the third-party system received the alert.
-
From your Kontakt.io Launchpad, select the relevant Kio App > navigate to the Alerts menu, select the List view > locate and select the alert activated in step 1 > view its Activity Timeline > verify the Webhook event is present and view its details.
-
Go to Kio Cloud Company Settings > navigate to the Webhooks menu > select the History Log tab > verify the alert event details and a successful status (200).
When an alert is triggered by an Alert Rule with an assigned Webhook, you can view the Webhook event from the alert's profile.
-
From your Kontakt.io Launchpad, select the Staff Safe Emerg. Call app.
-
Navigate to the Alerts menu, select the List view.
-
Locate and select the alert > view its Activity Timeline > locate the Webhook event and view its details.
-
From the Activity Timeline > locate the Webhook alert event(s).
Each event response/status provides an option to show details for additional information.