Introduction to custom webhooks

Introduction

What is a webhook?

Webhooks in Entuity

Prerequisites

Workflow high level overview

Tool permission requirements

Custom webhooks across servers and config sets

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 event 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. See this article for more information on user permissions in Entuity.

Custom webhooks across servers and configuration sets:

From Entuity v23.0 P03 upwards, you can configure and manage custom webhooks on a server or with a configuration set using the Server/Configuration Set dropdown field at the top-left of the Custom Webhooks page. 

With a configuration set, you can share your custom webhook configuration across the servers in the configuration set. A custom webhook configuration comprises the custom webhook group definitions, including all the rules, conditions, and events for each custom webhook group.  

See this article for more information on centrally managing custom webhooks with configuration sets.

Note, for events to be raised on any server in a configuration set, Entuity recommends that the only custom webhook configuration on the server must be the custom webhook configuration of the configuration set to which the server belongs. If other custom webhook configurations exist, then synchronization of the configuration set takes priority in the database.

To access the Custom Webhooks page:

1. From the Main Menu, click Administration.
   The Entuity Administration page is displayed.

2. In the Events section of the page, click Custom Webhooks.
   
   
    

   The Custom Webhooks page is displayed.

This page consists of four 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 lists 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 has 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 (for example, 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 has the following columns:

Webhook Endpoints table:

This table has the following columns:

From this tab, you can add, edit, and delete webhook groups and their endpoints. See this article for more information on creating, editing, and deleting webhook groups and webhook endpoints.

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

From this tab, you can also manually export and import your custom webhook configuration (from Entuity v23.0 P03 upwards). For more information on manually exporting and importing a custom webhook configuration, 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, view its details, and create a rule for that payload. See this section later in this article for more information about rules. From this tab, you can also upload custom payloads.

To view details of a particular payload:

1. Select the payload for which you want to view details and click Create Rule at the top of the tab or from the Overflow Menu.
   Note, for Entuity versions earlier than Entuity v20.0 P02, use the Details button or Overflow Menu option to view payload details.  
2. From the payload tree page that is displayed, review the full payload that is shown in expandable tree format, allowing you to drill down into the details thereof. 
   This page displays the payload (as JSON/XML type) in a tree, and allows selection of entries in the tree. From the payload tree page, you can 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 from RESTful API will not be stored in the database.

You can also upload your own payloads from the Payloads tab. See this article for more 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.

See this article for more information on creating, editing, and deleting custom webhook rules.

The table on the Rules tab has the following columns:

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 from 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:

RESTful API:

See the following articles for more information on managing custom webhooks using 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