How do I add, edit, or delete a custom webhook mapping rule?

Introduction

To create a custom webhook mapping rule

To edit a rule

To delete a rule

RESTful API

Introduction

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). This is a custom webhook event, which is not the same as an out-of-the-box Entuity event or a custom Entuity event.

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

Click the Rules tab of the Custom Webhooks page 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.

Note, a webhook event receives an integer event ID when created. If you have a multi-server environment that requires event IDs to be identical across servers (for example, if you plan to use custom webhook events in EMS triggers or rules), then Entuity recommends you only configure custom webhooks with configuration sets for those servers. For more information on managing custom webhooks in a multi-server environment, see this article.

The Create Rule functionality can be found on the Payloads tab of the Custom Webhooks page. 

To create a custom webhook mapping rule:

1. Navigate to the Payloads tab of the Custom Webhooks page.
2. If you don't have a multi-server environment, skip to the next step. Otherwise, from the Server/Configuration Set dropdown field at the top-left of the page, select the server or configuration set for which you want to create a webhook mapping rule.

3. Select the payload for which you want to create a rule and click Create Rule at the top of the tab (or from the Overflow Menu or right-click Context Menu). For more information on how to upload a payload, see this article.
   Note, you can't create a rule for a server that's in a configuration set. Instead, you must select the configuration set itself to create a rule.
   
   
    

   A new Payloads tab is displayed. 

   From here, you can select an item, or items, from the payload on which you can base a rule (if applicable) (see Event Source and Event Details field descriptions later in this article), or you can advance to creating a rule without selecting an item by clicking Next.
   
   
   
   Note, some payloads won't have any items to select. In this case, you can still click Next.
   
   
    

   The Create Rule form is displayed.
   
   
    

Event Rule

1. From the Group dropdown field, select the webhook group to which this rule will apply. If a payload is used for this rule, the Group selection will be made automatically.
2. Specify a Rule Name. This must be a unique name, different from that of any other webhook rule within the selected webhook group.
3. Click the Conditions field to open the Conditions form. 
   The conditions determine whether the payload meets the requirements for raising a webhook event. At least one condition is required for a rule. Do the following, and then click Done:
   1. Click +Add Condition to add a new condition, or select from an existing condition in the list. If you are adding a new condition, you can specify the following parameters:
   2. Field - the key from which the value will be retrieved. If you have selected entries in the payload tree, these will be accessible from the Field dropdown.
   3. Type - specify the type into which the value will be converted, from the following:
      • Int32
      • Int64
      • Float
      • Double
      • String.
   4. Operation - specify the operation that the value will use, from the following:
      • = [equals]
      • != [not equals]
      • like [if Type is 'String']
      • > [greater than] [if Type is not 'String']
      • >= [greater than or equals] [if Type is not 'String']
      • < [less than] [if Type is not 'String']
      • <= [less than or equals] [if Type is not 'String']
   5. In the Value to Match field, specify the value to compare to the value from the payload.

4. Specify whether to enable the rule with the Enable Rule toggle.

    

Event Mapping

Note, in Entuity versions earlier than v23.0 P03, you could only create an event in the Event Mapping section of the Create Rule form. From Entuity v23.0 P03 upwards, you can either select from a list of existing events or create a new event. As a result, the Event Name, Severity, and Event Description fields are now located on the Select Event form, described next.

1. Click the Event field to open the Select Event form, where you can either select an event from a list of existing events in the group, or create a new event: 
   
   
2. Select an existing event from the list or create a new event by setting the Create new event toggle to Yes and filling in the following fields:
   • Event Name - enter the name of the event that you want to create.
   • Severity - specify the severity of the new event, from the following:
     • Info
     • Minor
     • Major
     • Severe
     • Critical
   • Event Description - enter an informational description of the event that you want to create. This content is then displayed in the Event Description column of the Events List dashlet table.
3. Click Done to save your changes and return to the Create Rule form.
4. Specify the Event Source and Event Details for the event - these are informational entries that are then displayed in the Event Source and Event Details columns of the Events List dashlet table respectively. If you selected an item from the payload before opening the Create Rule form, you can select it here. 
   
   In the following example, both host and scnEq are selected, which are now accessible in these fields:
   
   
   
   
   
    
5. You can specify whether to attach a payload with the Attach Payload field. Enabling this field attaches the webhook payload to the generated event as a custom attribute 'webhookPayload'. By attaching the payload to the generated event, you can then create generic-type event rules in the Entuity Event Management System (EMS) that look to and use the event's custom attribute(s) for further purposes, such as to re-raise or redirect the generated event to another managed object.
   • For example, if you have a custom webhook rule set up to raise events upon receipt of webhooks from a specified device X that is managing other devices Y and Z, you can attach the payload information to the event that can then raise events on devices Y and/or Z when appropriate. The required custom webhook rule is specified in the Conditions section of the rule, and the payload message information is accessed via the Action Steps section.
   • In the following example of a custom event rule that accesses a webhook payload, the custom webhook rule 'Webhook Message' is invoked in the Conditions, and the payload information itself is accessed from execution of groovy script in the Action Steps:
     
     
     
      
6. Click Done on the Create Rule form to save your changes. Otherwise, click Cancel.

To edit a rule:

1. Navigate to the Rules tab of the Custom Webhooks page. 
2. If you don't have a multi-server environment, skip to the next step. Otherwise, from the Server/Configuration Set dropdown field at the top of the page, select the server or configuration set for which you want to edit a webhook mapping rule.
3. Select the rule that you want to edit and click Edit Rule at the top of the page (or from the Overflow Menu or right-click Context Menu).
   Note, you can't edit a rule for a server that's in a configuration set. Instead, you must select the configuration set itself to edit a rule.
   The Edit Rule form is displayed. This form contains the same fields as when adding a rule.
4. Make your changes and then click Done. Otherwise, click Cancel.

To delete a rule:

If you delete a webhook rule, it will not delete the webhook group.

1. Navigate to the Rules tab of the Custom Webhooks page. 
2. If you don't have a multi-server environment, skip to the next step. Otherwise, from the Server/Configuration Set dropdown field at the top of the page, select the server or configuration set from which you want to delete a webhook mapping rule.
3. Select the rule that you want to delete and click Delete Rule at the top of the page (or from the Overflow Menu or right-click Context Menu).
   Note, you can't delete a rule from a server that's in a configuration set. Instead, you must select the configuration set itself to delete a rule.
4. At the confirmation window, click Yes to confirm the deletion. Otherwise, click No.

RESTful API:

See the following articles for more information on managing custom webhook groups using Entuity RESTful API:

• List and create custom webhook rules
• Inspect or delete a custom webhook rule