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

Introduction

To add 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 an webhook group. All rules in an webhook group are evaluated against a received payload, stopping at the first one to succeed.

Click the Rules tab on 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.

From Entuity v20.0 P02 upwards, the Create Rule functionality can be found under the Payloads tab of the Custom Webhook page. For Entuity v20.0 GA and P01, this functionality can be found under the Rules tab.

To add a custom webhook mapping rule:

1. Entuity v20.0 GA : Navigate to the Rules tab. Click Create Rule at the top of the page (or via the Overflow Menu).
   
   Entuity v20.0 P02 upwards : Navigate to the Payloads tab. Select the payload for which you wish to create a rule and click Create Rule at the top of the page (or via the Overflow Menu or right-click Context Menu).
   
   
   
   
2. This will open a new Payloads tab. From here you can select an item or items from the payload on which you can base a rule (if applicable) (see Event Source, Event Details, and Event Description in the Create Rule form as detailed below), or you can simply advance to creating a rule without selecting by clicking Next.
   
   
   
   Note, some payloads will not have any items to select. In this case, you can still click Next.
   
   
   
   
3. This will open the Create Rule form on the right side of the page.
   
   
   
   

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 to that of any other webhook rule within the selected webhook group.
3. Click the Conditions field to open the Conditions form. The conditions will determine whether the payload meets the requirements for raising a webhook event. At least one condition is required for a rule.
   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 - dropdown field specifying the type into which the value will be converted, either:
      • Int32
      • Int64
      • Float
      • Double
      • String.
   4. Operation - dropdown field specifying the operation that the value will use, can be:
      • = [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 Rule.

Event Mapping

1. From the Event Name dropdown field, enter the name of the event to be created.
2. Specify the severity of the event being created from the Severity dropdown field, selecting from one of the following:
   • Info
   • Minor
   • Major
   • Severe
   • Critical
3. Specify the Event Source, Event Details and Event Description for the event to be created - these are informational entries that will appear in the Event Source, Event Details and Event Description 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, e.g. in the following example, we selected both host and action, which are now accessible in these three fields:
   
   
   
   
   
   
4. From Entuity v21.0 P01 upwards, you can specify whether to Attach Payload. Enabling this field will attach 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, e.g. 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 below example of a custom event rule that accesses a webhook payload, the custom webook rule 'Webhook Message' is invoked in the Conditions, and the payload information itself is accessed via execution of groovy script in the Action Steps:
     
     
     
     
5. Click Done to save your changes, otherwise click Cancel.

To edit a rule:

1. Navigate to the Rules tab of the Custom Webhooks page. Select the rule that you want to edit and click Edit Rule at the top of the page, or via the Overflow Menu or right-click Context Menu.
2. The Edit Rule form will open on the right of the screen. This contains the same fields as when adding a rule.
3. Make your desired 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. Select the rule that you want to delete and click Delete Rule at the top of the page, or via the Overflow Menu or right-click Context Menu.
2. A dialog window will appear, asking you to confirm your choice.

RESTful API:

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

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