The UXI Dashboard can send information to a third-party service via webhooks. Currently, there are pre-defined webhooks for Slack, Teams, ServiceNow, or a generic webhook that can optionally use HTTP Basic authentication and send the messages in a predefined JSON format.
The content of the webhook message depends on whether your dashboard is using Incident Detection. Incident Detection examines issues based on your historical data to identify anomalies and group issues together. Without Incident Detection, webhooks notify you of all issues detected for every sensor.
With Incident Detection enabled, instead of being notified about every issue, you are only notified about each incident when it is first detected and when it is resolved. Please note that incidents can evolve, and more issues may be added to the incident after it is first detected, but no subsequent updates will be sent.
If you want more granular data than the data provided by webhooks, please see the Data Push Destinations feature using the Issue data.
Adding Webhooks
Webhook 1: Generic
Before you begin with the generic webhook, ensure the system you want to use is reachable from our UXI cloud. The following UXI IP addresses should be allowed to communicate with the destination.
54.190.18.21
52.88.224.46
54.71.247.190
34.210.97.95
To set up the webhook from the dashboard, go to Settings > Integrations and select the Add Webhook button.
Change the target to Generic.
Paste the webhook URL in the URL input field.
Select an authentication method: None or Basic Auth.
Bearer Token authentication: If the destination allows it to be specified in the URL as a query parameter, you can include it in the URL. This won’t work if the destination only allows it to be part of the header.
Click on Add.
Your webhook should be visible in your webhook list and will be triggered once an issue or incident is detected depending on whether Incident Detection is enabled.
Below is an example of the body of the request to the webhook URL for dashboards without incident detection enabled.
{
'details': ' Sensor: *Sensor1* Network: *YourSSIDName* Service: *Gmail*',
'notification_reference': 5649,
'description': 'External service is unavailable',
'severity': 'error',
'status': 'ALARM',
'start_timestamp': 1590395448
}Below is an example of the body of the request to the webhook URL for dashboards with Incident Detection enabled.
{
"description":"*New incident detected*",
"details":"New incident detected\n'Incident JUL/2024-026'\n3 sensors affected\n\nIssues:\nGATEWAY_UNREACHABLE\nNetworks affected:\n• uxi_psk\nGroups affected:\n• Group1\n• Group2\n• Group3\n\nIncident began: 2024-07-15 06:45:31.105569+00:00\n",
"notification_reference":"cd5c2826-0f0e-4bd1-ba64-b0a02f040842",
"severity":"error",
"status":"ALARM",
"start_timestamp":1721025931.105569
}
Webhook 2: Microsoft Teams Incoming Webhook (Updated using Microsoft Workflows)
In Microsoft Teams, you can create a workflow to receive webhooks from the UXI dashboard and post them into a Teams channel.
Go to Microsoft Teams > Workflows > Click “Create New flow”
Click “Create from Blank”
Search HTTP Request and select Request
Select “When an HTTP request is received.”
Who can trigger the flow? Select Anyone
Request Body JSON Schema:
Click the “Use sample payload to generate schema” link.
In the open dialogue, copy and paste the following sample payload in the given box and press “Done”.
{"text": "A notification from UXI system"}
Now the schema should look like this:
Schema:
{
"type": "object",
"properties": {
"text": {
"type": "string"
}
}
}
Click “Add New Step” and then search and Click “Post a message in a chat or channel” in the choose an operation search.
Post as: Select Flow bot
Post in : Select Channel
Team: Select Your Team name of interest.
Channel: Select Channel Name of interest. Ensure that it is a public channel (everyone within the team is able to see the messages, but not external people) If it is a private channel you can try posting as "user" instead of flow bot.
The results will look similar to:
Message:
Click in the Add message box and follow it to open the “Add dynamic content” pop-up.
Then click the “text” shown in the open pop-up.
The result look similar to:
You can also type in prefix message, like: UXI Alert for Issue/Incident before
the dynamic text field.
Click Save and it will generate the webhook URL on the first step.
Copy the URL.
In the UXI Dashboard, navigate to Settings > Integrations > Webhooks > Microsoft Teams and setup a teams webhook using that URL.
The results should look similar to:
Once the webhook starts working you should receive messages in your channel from UXI
Once you have incidents on the dashboard, you should be able to receive the webhook messages in the Teams channel. You can validate this by checking the incident panel on the top right side of the UXI dashboard.
Webhook 3: Slack
In order to add a Slack webhook, you need to create a Slack application.
Follow the instructions for Slack incoming webhooks here.
Copy the webhook URL generated by Slack.
It should look something like this:
https://hooks.slack.com/services/xxxxxxxxxx/xxxxxxxxx/xxxxxxxxxxxxxxxxxxxxxxxx
On the dashboard, click on the Add button.
Change the target to Slack.
Paste the URL in the URL input field.
Select None for Authentication.
Click on Add.
All alerts will now be published to the appropriate Slack channel. In our case the channel is #webhook-test and the result is as below
Webhook 4: ServiceNow
This is a little more in-depth as it requires configuration on ServiceNow.
Navigate to Scripted REST API
Create your API
Click on the New button to start creating your API.
Give your API a Name and an ID.
Click on the Submit button to save this API.
Select your API and create a new unauthenticated resource
After creating your API, you are redirected to a list of APIs.
Search for your API and select it.
Create a new resource by clicking on the New button at the bottom of the page.
Use the script below as a template
This example shows how to create a POST request. We will be using it to post an alert. The alert details are contained in:
request.body.data.text
Final script for REST API
(function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {
gs.info(request.body.data);
var action = request.body.data.action;
var inc = new GlideRecord('incident');
if (action == 'open_incident') {
inc.initialize();
inc.short_description = 'Incident created from WebHook';
inc.comments = request.body.data.text;
inc.insert();
gs.info('Incident created');
return {
"uri": request.uri,
"url": request.url,
"sys_id": inc.sys_id,
};
} else if (action == 'close_incident') {
inc.get(request.body.data.sys_id);
inc.state = 7;
inc.update();
gs.info('Incident closed');
}
})(request, response);
An example Incident from ServiceNow
Once this is done, add the webhook to the dashboard.
Adding webhooks on the dashboard
Change the target to ServiceNow.
Paste the Webhook URL in the URL input field. In this case, use https://ven02658.service-now.com/api/arune/cape. This URL is a combination of the base (https://ven02658.service-now) and the resource path (/api/arune/cape).
Select the Authentication method for your webhook:
If None is selected, proceed to the next step.
If Basic is selected, enter the Username and Password.
Click on Add.
All alerts will now be published to the defined URL. Please note that incidents on ServiceNow will auto-close when all issues on an alert (incident) have been closed or are no longer ongoing.
Note: Some webhooks, when configured using a generic option, require data to be received in a specific JSON format (e.g. MS Teams Webhook). Feature requests for such configurations can be entered in AIZ.
Editing webhooks
In the Webhooks section, click on the webhook you would like to edit. This opens the edit modal, where you can modify the webhook.
Click Save to save your changes.
Deleting webhooks
In the Webhooks section, click on the webhook you would like to delete.
This opens the "Edit" modal, where you can click on the red trash can to remove the webhook. Please note that this will not delete the configuration on your service side.