Introduction to custom webhooks

 

Introduction

What is a webhook?

Webhooks in Entuity

Prerequisites

Workflow high level overview

Tool permission requirements

To access the Custom Webhooks page

RESTful API

 

 

Introduction:

From Entuity v20.0 upwards, you can add webhooks from any device vendor, application or service to the Webhook page, and turn that webhook into an event. This functionality is available from the Custom Webhooks page. This complements the hardcoded webhooks detailed in the existing Webhooks page.

 

 

What is a webhook?

A webhook is an address (URL) provided by a server application that can be used by an external service to ‘push’ notifications to the server using HTTP POST.

 

 

Webhooks in Entuity:

In Entuity, you can create a webhook endpoint associated with a device that can generate HTTP notifications.

You can then specify rules which can process those notifications and turn them into Entuity events which will be handled by the Event Management System.

 

 

Prerequisites:

To configure webhooks in Entuity you will need a device which is capable of sending notifications using HTTP POST with a JSON payload (and from Entuity v20.0 P02 upwards, XML). This device must be managed within Entuity.

You will need access to both the management dashboard of the device and administrator access to Entuity.

The device will need to be able to make web requests of the server running Entuity. Note, in the case of cloud managed devices the cloud controller will need to be able to resolve the URL of the Entuity server in your network.

 

 

Workflow high level overview:

1. Manage the device in Entuity.
2. Create the webhook group and webhook endpoint for the device in the Entuity webhook administration interface.
3. Copy the generated endpoint URL.
4. From the device's administration dashboard, create a webhook alert, paste in the webhook endpoint URL and configure the alert to send data to that URL.
5. Once webhooks have been received in the Entuity server, you can use a recent payload to configure event rules.
6. When a notification matching the configured rule(s) is received by the Entuity server, a corresponding rule will be generated in the context of the managed device.

 

 

Tool permission requirements:

The Webhook Administration tool permission is required in order to access the Custom Webhook page and to create, edit and remove webhooks. Please see this article for further help and information on user permissions in Entuity.

 

 

To access the Custom Webhooks page:

1. Click the Main Menu and then Administration.
2. On the Administration page, click Custom Webhooks.
   
   
   
   
3. This will open the Custom Webhooks page.

 

This page consists of 4 tabs:

• Groups
• Payloads
• Rules
• Events

 

Groups:

The Groups tab is the default tab that is displayed when you navigate to the Custom Webhooks page. This tab displays your existing webhook endpoint groups and the individual webhook endpoint(s) associated with each Webhook Group. Each individual endpoint is a URL assigned to a specific managed device.

This tab displays two tables:

• The top table displays your Webhook Groups. These groups dictate the type of device and what rules will be run on payloads originating from endpoints registered to it (e.g. Meraki devices).
• The bottom table displays your Webhook Endpoints. These are the devices registered to the webhook group selected in the top table, each creating a URL. If you select multiple webhook groups, then the bottom table will display all the endpoint devices from the selected groups.

Webhook Groups table:

This table consists of the following columns:

Column Name	Column Description
Group Name	name of the webhook group.
Server	name of the server on which this group exists.
Endpoint Count	number of endpoints registered to this group.
Rule Count	number of rules registered to this group.
Status	status of the group (e.g. number of payloads received).

 

Webhoook Endpoints table:

This table consists of the following columns:

Column Name	Column Description
Device Name	name of the device that is bound to the webhook group
Group	group to which the device is registered.
URL	URL to be used for payloads
Payload Collection	if payloads should be stored.
Payload Max	number of payloads to store.
Payload Exists	number of payloads currently stored
Authentication	authentication status of the device (e.g. Secret Key).

 

From this tab, you can add, edit and delete Webhook Groups and their endpoints. Please see this article for help and information on creating, editing and deleting webhook groups and webhook endpoints.

For help and information adding and removing devices to/from a webhook group, please see this article.

 

 

Payloads:

Click the Payloads tab to see a list of received webhook payloads. The payload is the data received from the endpoint device, in JSON (and from Entuity v20.0 P02 upwards, XML). This tab displays any payloads that were sent to an endpoint device that had payload collection enabled. You can select a payload and view its details. From this tab, you can also upload custom payloads.

To view details of a particular payload:

1. Select your preferred payload in the table and then click Details via the button above or from the Overflow Menu.
2. The full payload will be displayed in expandable tree format, allowing you to drill down into the details thereof. It displays the payload (as JSON/XML type) in a tree, and allows selection of entries in the tree. From the Payload Details, it will be possible to create a new mapping rule for generating a specific Entuity event using this payload as a guide.

From Entuity v20.0 P02 upwards, an invalid payload received via RESTful API will not be stored in the database.

You can also upload your own payloads. Please see this article for help and information on uploading payloads.

 

 

Rules:

You can specify custom webhook rules so that a specific Entuity event is generated whenever a specific payload is received (and particular conditions pertaining to that specific payload are met).

A rule is associated with an endpoint group. All rules in an endpoint group are evaluated against a received payload, stopping at the first one to succeed.

Click the Rules tab to see a list of webhook mapping rules. A webhook mapping rule comprises the following:

• the definition of an Entuity event type.
• a mapping that allows this event to be populated from the payload fields.
• a list of conditions that are used to evaluate the payload, to see if it meets the requirements to generate the event.

Please see this article for help and information on creating, editing and deleting custom webhook rules.

The table on the Rules tab has the following columns:

 

Column Name	Column Description
Name	name of the rule.
Group	endpoint group to which the rule belongs.
Server	server on which the endpoint group exists.
URL	rule's URL.
Condition	text representation of the rule's conditions.
Enabled	if the rule is enabled, either true or false.

 

 

Events:

The Events tab displays a list of webhook events generated by the webhooks, according to the webhook rules specified for each individual webhook event. Note, this does not list instances of events that are generated, but rather details the specified webhook event definitions themselves.

Also note that a custom webhook event is different to an out-of-the-box Entuity event or a custom Entuity event.

From Entuity v20.0 P02 upwards, custom webhook events are listed under the Events tab of the Event Administration page as they are created (and disappear when they are deleted). You can also forward custom webhook events to third party event receivers.

The table has the following columns:

Column Name	Column Description
Name	name of the event.
Description	description of the event.
Group	endpoint group on which the event was raised.
Severity	severity of the event, i.e. Info, Minor, Major, Severe or Critical.

 

 

RESTful API:

Please see the following for help and information on managing custom webhooks via Entuity RESTful API:

• List and create custom webhook groups
• Inspect or delete a custom webhook group
• List and create custom webhook rules
• Inspect or delete a custom webhook rule
• List all custom webhook endpoints
• Modify a specify custom webhook endpoint
• List all custom webhook endpoints for a specified webhook group
• List all custom webhook events
• Modify a specified custom webhook event
• Inspect information about events for a specified custom webhook group, and add a webhook endpoint to a specified custom webhook group
• List custom webhook payloads
• Create custom webhook payloads