Integrating Webhook Events from External Systems

As a systems administrator, how do you integrate your CRM, monitoring tool or ticketing tool with the Automation Engine? AWI lets you create Webhook Event objects, that enable you to integrate your external system webhooks with the Event Engine. The Webhook Event object can listen and retrieve webhook event payloads from external systems in real time.

The following high-level view diagram shows how a webhook event payload is dealt with by the Event Engine and Automation Engine:

High level view diagram shows how a webhook event payload is dealt with by the Event Engine

This example is an example of service orchestration using capabilities of the Automic system. Service orchestration is characterized by an automated process that runs across multiple platforms, domains, and applications to deliver an IT service. For more information, see About Service Orchestration.

This page includes the following:

To use the Webhook Event feature, the following components and knowledge are required:

  • An installation of Analyticswith the Rule Engine See: Installing Analytics Manually

  • Ensure the following action packs are installed. You should see them in the PACKAGES folder in the Explorer sidebar in the Process Assembly perspective.

    • PCK.AUTOMIC_ANAYLTICS (Analytics Action Pack)
    • PCK.AUTOMIC_RULE_SIMPLE (Event Engine Rule Simple)
      This action pack contains predefined object templates to build a simple conditions (like >, >=, =) on the incoming event driven rules. Use the rules to trigger an AE executable object.
    • PCK.AUTOMIC_RULE_STATECHANGE (Event Engine Rule State Change)
      This action pack contains predefined object templates to enable you trigger actions based on the state of an executable object or service.

    Note: If they are not listed in the Explorer sidebar, then you need to download them from our marketplace at https://marketplace.automic.com/ and install them. For instructions about installing an action pack, see Installing Packs in Working with Packs and Plug-ins.

  • Prior implementation knowledge of Event and Variable(VARA)objects
  • A good understanding of webhooks and how they are implemented
  • Access to an external system that enables the use of webhooks
  • Knowledge of the JSONPath syntax
  • Knowledge of your external system JSON schema

For further information, see: WEBHOOK Events

Create an IA Event Definition

The IA Event Definition represents an event structure. The Event Engine uses the event structure to trigger Rules and execute jobs, scripts, and workflows and so on.

The following steps show you how to build an Event Definition using webhooks from your external system event payload.

  1. Log in to an Automation Engine Client where an IA Agent is assigned. See: Assigning Clients to Agents

  2. Click Process Assembly in AWI

    • Click Add Object from the toolbar
    • Select and expand Variable tree Administration perspective
    • Select and expand XMLvariables, then select IA > EVENT_DEFINITION Variable

  3. To build an IA Event Definition from your webhook event payload, you must have prior knowledge of the payload content. Download a test event payload using a previously defined endpoint, or use your system guide to understand its schema.

    Note: The event payload is in the JSON format. To map the Key Attributes, you must have prior knowledge of JSONPath syntax.

    Example:
    The following example shows an Event Definition page (left) and a webhook event payload in JSON (right). This information helps you deduce how to build your Event Definition.

    Important!

    • When defining your Key Attributes, your event payload is displayed in a structured schema. You must define your Attribute Keys into a flat schema.
    • Although there is no rule for naming Key Attributes, we recommend that you name them as they appear in the JSON. This practice enables you to map them easily when you create a Webhook Event object.

    Identifying JSON fileds to build the Event Definition
    Enter the following details into the Event Definition sheet, keep in mind what you aim to achieve when external events are received:

    • Attribute Key: Key value pair (for example, application message, status event, acknowledgment and so on)
    • Description: Optional
    • Type: You can either select String, Number, or Boolean in relation to your Attribute Key

  4. Click Save after you have completed your Event Definition.

For further information about Event Definition, see: IA Event VARA Objects

Create, Map, and Filter a Webhook Event

A Webhook Event generates an endpoint for an external webhook to send payloads to the Event Engine to be processed. The following step-by-step shows you how to create, map values using JSONPath and filter received payloads.

  1. In AWI, click Process Assembly.

    • Click Add Object from the toolbar
    • Select and expand Event (EVNT) tree
    • Select and expand IA variables, then select WEBHOOK Event

    Note: To secure the Webhook endpoint see: Securing the Backend. The Webhook runs on the IA Agent and uses the same TLS/SSL settings. If you want to use different certificates for each Webhook, install multiple IA Agents and use the certificate on each agent.

    Two sections are in the Webhook Event object sheet:

    • Endpoint Information
      • Path
    • Map Received Data to Event Definitions
      • Event Definition
      • Filter Received Data with conditional operators
      • Map Values using JSONPath
  2. Endpoint Information - Path:
    When a new Webhook Event object is created in AWI, a URL is generated with a unique Path. The unique path is generated using the Automation Engine Client ID login and a unique number. This entire URL (including the path) is used in your external system webhook URL configuration.

    The structure of the URL is as follows:

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

    Example:
    The following example shows endpoint (url+path) structure.

    The following example shows endpoint (path) structure.
    Example:
    The following example shows endpoint (url+path) structure as it appears in AWI

    The following example shows endpoint (path) structure as it appears in AWI


  3. Map Received Data to Event Definitions - Event Definition Selection:
    In the Webhook Event object sheet, select the Event Definition to begin the JSONPath mapping and filter process. The Event Definition contains your defined Attribute Keys.

    Example:


  4. Map Received Data to Event Definitions - Filter Received Data
    This feature lets you filter received event payloads using basic conditional operators. If the filtered conditions pass, they are then used to trigger Rules for incoming events.

    Note: The filter Operators are defined on the Simple Rule page.

    To apply a filter, you must first select a JSONPath from the received payload. The JSONPath can be selected by manually entering the path using the autosuggestion, or by the JSONPath Builder and the Create Expression button.

    Autosuggestion
    If you enter the JSONPath manually, you must have knowledge of the received payload schema and JSONPath. The autosuggestion feature can help you to create a JSONPath expression, however it will not be able to evaluate it.

    JSONPath Builder
    Using the JSONPath Builder, you are able to make the following operations:
    • Copy and paste a JSONPath sample into the editor
    • Manually enter an expression and evaluate it using the Expression box
    • Filter Received Data by selecting a line in the editor and click the Create Expression button to auto-generated an expression and result
    • Map Values using the select a line in the editor and click the Create Expression button to auto-generated an expression and result

    Examples:
    In the following example the phoneNumbers line is selected. After clicking the Create Expression button, the phoneNumbers array is evaluated and an Expression and Result is generated.

    Creating Filters

    If you use the JSONPath Builder in the Filter Received Data section, you can use the generated expressions to quickly create filters.


     



    Example:
    The following example filter is based on a webhook event in the JIRA application called Issue_created. If a JIRA event payload with the event name issue_created is received, it triggers a Rule in the Event Engine.

    This feature allows you to filter received event payloads based on conditional operators.

    Note: The deep scan operator ".." is not supported for filter expressions. For information, see here.

    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 event types.

    Example:
    The following example shows an external repository application that is configured to send two event payloads (Push and Modified) to one URL (endpoint).
    External repository configured to send two event packages (Push and Modified) to one URL (endpoint)

  5. Map Received Data to Event Definitions - Map Values Using JSONPath Builder:
    Once you have selected the Event Definition, you see your previously created Attribute Keys listed. The next task is to map the Attribute Keys to the JSONPath of the incoming event payload. Mapping is necessary because Event Engine rule logic only works on events in the Event Definition format.

    Mapping Values using the JSONPath Builder

    If you use the JSONPath Builder in the Map Values Using JSONPath section, you can quickly map Event Definition Attribute to a JSONPath.



    Example:
    In the following example, each Event Definition Attribute Key has been mapped to its corresponding JSONPath.

    In the following example, each Event Definition Attribute Key has been mapped to its equivalent JSONPath.
  6. Select the Attributes tab and select the IA Agent

  7. Save and then Execute the Webhook Event.

Create a Rule

Rules are building blocks that consist of rule logic. One way of looking at rule logic is to imagine a set of instructions (or a formula) that follows certain inferences. An example would be: IF some condition is met THEN take some action.

Two Rules types can be used to trigger an Event:

Note: To install the Analytics Action Pack Rules see: Installing an Event Engine Rule.

All rules share the following features:

  • They execute an Automation Engine Object whenever the rule triggers
  • A rule type is defined by a set of parameters that can be easily mapped to the PromptSet values of the selected AE Object
  • A rule type offers a defined set of output parameters

  1. Select and Add the rule type from the list

    2. Add Rule Object

  2. Configure the rule (based on the selected rule type). Configuration is further outlined in detail with use case examples defined. See: RULE Events

    Example:
    Continuing with the UI message example, If the event type is equal to "repo: msg_change" the Rule is triggered and executes a job that creates a ticket for the translation team.

    Defining a Rule

  3. Save your created rule

  4. Execute the rule and check if the rule is running by opening the Executions

  5. Whenever a rule is triggered, a new child execution is generated. You can open a child execution task to see the AE object executed by the trigger
  6. The "Event Count" increases each time that the rule is triggered
    Event Count Trigger

Note: The Event Count does not increase for every event that the rule might be listening on.