WEBHOOK Events

As an Automation and Event Engine user, the Webhook Event object lets you build your own endpoint to receive event payloads from external systems or sensors. Once the Webhook object is configured, it can process any JSON message received via HTTP. The Webhook Event object feature makes integrating external systems easier and averts you from building a specific collector.

There are some prerequisites to consider before you use the Webhook Event, see:

• An installation of Analytics with the Rule Engine. See: Installing Analytics and the Event Engine
• The Analytics Action Pack, Rule Pack and AWI Plug from Marketplace

Webhook Event Object Use Cases

It can be used to integrate with systems that support webhooks. Once your system integration is configured, you will be able to receive and process events along with notifications in real-time.

Practical systems where real-time event notification could be beneficial:

• ticket management systems - customer orders, deliveries and so on
• monitoring tools - alarms, incidents and reminders
• CRM systems - new customer information and sales updates

Webhook Events can also be used with any application that can send JSON messages via HTTP. You can build your own sensors and process the data in a central place.

Webhook Event Object Overview

The following overview describes the UI labels and how the Webhook object works.

For more information, see Integrating Webhook Events from External Systems.

Endpoint Information (Path)

The Webhook object uses the IA Agent (when executed) to listen on a specific URL, and react to real-time incoming payloads. The structure of the URL is as follows:

IA Automation Agent address/ + "analytics/api/" + version of the API (currently "v1") + client no. /+unique no.

The Path consists of:

• The Automation Engine Client ID where the object was created
• A unique generated number
  

Example

/analytics/api/v1/100/1003106

Notes:

• The path cannot be edited
• The path is unique for each Webhook Event object

Mapping to Event Definition

Event Definition

The Event Definition is the basic building block of the Event Engine. It represents the Event structure that the Event Engine uses to trigger rules and execute workflows and so on. An Event Definition should be selected from the UI and applied to the Webhook Event object you configured to receive data.

The Event Definition's Attribute Keys should to be based on the anticipated event payload from the external system. As previously noted, you should have some prior knowledge of the incoming JSON message schema.

Mapping is necessary because Event Engine rule logic only works on events in the Event Definition format. Rules are triggered once the Event Definition is assigned to the received message. To map you need to know the content of the incoming event payload, along with the schema and the JSONPath syntax. The mapping process requires you transform the received structured data into a flat structure in the Webhook Event sheet.

Note: Mapping is covered in depth in Integrating Webhook Events from External Systems

It is also possible to map several external system event types by using the Add Mapping feature. Therefore you can register the same Webhook URL (endpoint) in your external system for multiple events types.

For more information, see IA Event VARA Objects.



Important! Prior knowledge of your external system JSON schema is required, otherwise mapping incoming messages will be time consuming and difficult.

Filter Received Data

Once the JSON message has been received, map the data to your previously created Event Definition Attribute Keys.

The filter consists of a set of conditions that will be evaluated when the event payload is received. If all of the conditions are met, the message will be mapped to the selected Event Definition and processed by the Event Engine.

Each condition consists of three parts:

• JSON path expression that will select data from the received payload
• Operator that will be applied to the data from the rest of the steps
• Provided text value that will compared with the result of the JSON path expression using the operator selected in the previous step

Note: The JSON message can be in any format.

To Execute a Rule

1. Select the Attributes page in the Rule Event object.
2. Select the IA Agent from the Agent combo box and click Save.



3. Click Execute to run the Rule.

Note: If you cancel or redeploy a rule, the Event Engine memory will be purged.

Securing the Webhook Endpoint

The Webhook runs on the IA Agent and uses the same SSL settings. If you want to use different certificates for each Webhook object you must install multiple IA Agents and use the certificate on each agent.

For more information, see Securing the Backend at Installing Analytics and the Event Engine.