Webhook Definition Manager

Add Webhook Definition

To add a new webhook definition, click to create.

1. Definition Type - select the webhook definition type based on the usage of the webhook definition for policies or traps. Definition Type can be Policy or Trap. The default value is set to Policy.

2. Webhook Definition Name - enter the webhook definition name.

3. (optional) Template - select a preconfigured webhook template to populate default data. Click the drop-down list to choose one of the following.
   

   1. Post to Slack

   2. Post to Slack w/ DI URL

   3. Post to Watson AIOps

      Destination URL field gets automatically populated with a sample URL format. Also, it provides the default body in field Body.

4. (optional) Description - enter the description of the webhook definition.

5. Destination URL - based on the option chosen in field Template, Destination URL field is automatically populated with a sample URL format . You are required to update the sample URL format with the exact URL of your Slack Destination. For example, https://hooks.slack.com/services/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. However, if you choose to not use the template, you must add the URL of your Slack Destination directly in this field. To activate incoming webhooks to post messages from SevOne NMS into Slack, Slack channel must be configured first to obtain the URL. Please refer to section Configure Slack Channel.
   
   Click for the list of acceptable URL variables for policy / trap webhooks.
   

   for Definition Type = Policy,

   General Variables

   • $clusterName - The cluster name of the triggered alert.

   • $alertId - The id of the triggered alert.

   • $alertMessage - The message of the alert.

   • $alertType - The origin of the alert. For example, system / flow / trap.

   • $alertState - The severity of the policy. For example, Emergency or Debug.

   • $occurrences - How many times this alert is triggered.

   • $assignedTo - To which user this alert is assigned to.

   • $deviceId - The device id of the triggered alert.

   • $deviceIp - The IP address of the device of the triggered alert.

   • $deviceName - The device name of the triggered alert.

   • $deviceAltName - The alternate name of the device that triggered the policy.

   • $groupName - The device group/device type that contains the device that triggered the policy.

   • $policyId - The id of the policy.

   • $policyName - The name of the policy which was triggered.

   • $thresholdId - The id of the threshold.

   • $thresholdName - The name of the threshold.

   Metric Policy Variables

   
   

   The following variables are only supported for metric policy alerts. They are not supported for flow policy-based alerts.

   • $objectId - The object id of the triggered alert.

   • $objectName - The object name of the triggered alert.

   • $objectAltName - The object alternate name of the triggered alert.

   • $objectDescription - The description of the object of the triggered alert.

   • $pluginName - The short name for the plugin. For example, SNMP.

   • $pluginDescription - The description of the plugin. For example, SNMP Poller.

   for Definition Type = Trap,

   General Variables

   • $clusterName - The cluster name of the triggered alert.

   • $alertId - The id of the triggered alert.

   • $alertMessage - The message of the alert.

   • $alertType - The origin of the alert. For example, system / flow / trap.

   • $alertState - The severity of the policy. For example, Emergency or Debug.

   • $occurrences - How many times this alert is triggered.

   • $deviceId - The device id of the triggered alert.

   • $deviceIp - The IP address of the device of the triggered alert.

   • $deviceName - The device name of the triggered alert.

   • $deviceAltName - The alternate name of the device that triggered the policy.

   • $trapEventId - The id of the trap event.

   • $trapIPAddress - The IP address of the trap sender.

   • $trapOIDText - The OID of the trap that triggered/clear the alert (OID in textual format).

   • $trapOIDNum - The OID of the trap that triggered/clear the alert (OID in numerical format).

   The following variables are not applicable for clear webhooks when the trap alert is acknowledged manually from Events > Alerts.

   • $trapIPAddress

   • $trapOIDText

   • $trapOIDNum

   IPv6 addresses

   IPv6 addresses contain colons. Due to this, they cannot be directly used in URLs because the colons conflict with both the protocol declaration (http:// or https://) and port numbers. Therefore, when a literal IPv6 address is used , encase it in a bracket. For example, http://[2001:db8::1]:80

   Known Issue related to TLS Certificate

   Golang uses the standard net/http package to test the API endpoint while making the webhook request.

   TLS certificates that rely on the legacy Common Name field are not supported by webhook tests. Instead, SANs (Subject Alternative Name) must be used.

6. Allow insecure webhook connection - select the check box to allow an insecure connection to the webhook URL. Leave clear to allow SSL verification check for the webhook URL.

7. Timestamp Format - choose the timestamp from the options provided in the drop-down list.

8. Time Zone - choose the time zone from the options provided in the drop-down list.

9. Under Proxy section, enter the values for the following fields.

   1. Proxy - enter the proxy URL with protocol, IP, and port number (if applicable). For example, http://myproxy:portnumber/.

   2. User Name - enter username for basic authentication of the proxy.

   3. Password - enter password for basic authentication of the proxy.

10. Under Headers section, enter the values for the following fields.

    Headers data is encrypted at rest; i.e., it can be used for Bearer and AWS4-HMAC-SHA256 based login.

    For Bearer, add corresponding key-value pair in field Custom Headers.

    1. (optional) Use Basic Auth - select the check box to use the basic authorization. Enter the user name and password if the check box is selected.

       • User Name - enter the username for basic authorization.

       • Password - enter the password for basic authorization.

       Use Basic Auth, User Name, and Password fields apply to basic authorization only.

    2. (optional) X-Auth-Token - enter the x-auth-token for authentication. For example, eyJhbGciOiJIUzUxMHqAuE8YY3zfCGTNVc...

    3. (optional) Custom Headers - enter list of key-value pairs in JSON format for setting the custom headers. For example, {"cust_key1":"cust_val1","cust_key2":"cust_val2"} or {"Authorization":"Bearer 678h","X-Laundry-Service":"dryclean"}.

    4. (optional) Cookies - enter list of key-value pairs in JSON format for setting the cookies. For example, {"cook1":"val1","cook2":"val1"} or {"Name":"admin","User-token":"abc"}.

11. Under Request Options section, configure the following.

    1. Request Method - select the request method from options GET, POST, PUT, PATCH, and DELETE.

    2. Content Type - click the drop-down list to choose the content type from the following options available.

       • application/json

       • application/x-www-form-urlencoded
         

       • application/xml

       • text/html

       • text/plain

       • text/xml
         

         Examples

         Based on Content Type, the variables can be encoded individually. In examples below, $deviceName and $deviceId are encoded based on the content type.

         Example: for Content Type application/x-www-form-urlencoded

         deviceName=$deviceName&deviceId=$deviceId

         Example: for Content Type application/xml

         <device>$deviceName</device>

         <deviceId>$deviceId</deviceId>

    3. Body - click for the list of acceptable message variables for policy / trap webhooks.
       

       If an unsupported variable is used, it is replaced with n/a. For example, $pluginName is only supported for metric policy alerts. However, if $pluginName is added in flow policy webhook, it will be replaced with n/a.

       for Definition Type = Policy,

       General Variables

       • $clusterName - The cluster name of the triggered alert.

       • $alertId - The id of the triggered alert.

       • $alertMessage - The message of the alert.

       • $alertType - The origin of the alert. For example, system / flow / trap.

       • $alertState - The severity of the policy. For example, Emergency or Debug.

       • $occurrences - How many times this alert is triggered.

       • $firstSeen - The first time this alert is triggered.

       • $lastSeen - The last time this alert is triggered.

       • $assignedTo - To which user this alert is assigned to.

       • $deviceId - The device id of the triggered alert.

       • $deviceIp - The IP address of the device of the triggered alert.

       • $deviceName - The device name of the triggered alert.

       • $deviceAltName - The alternate name of the device that triggered the policy.

       • $groupName - The device group/device type that contains the device that triggered the policy.

       • $policyId - The id of the policy.

       • $policyName - The name of the policy which was triggered.

       • $thresholdId - The id of the threshold.

       • $thresholdName - The name of the threshold.

       Metric Policy Variables

       
       

       The following variables are only supported for metric policy alerts. They are not supported for flow policy-based alerts.

       • $objectId - The object id of the triggered alert.

       • $objectName - The object name of the triggered alert.

       • $objectAltName - The object alternate name of the triggered alert.

       • $objectDescription - The description of the object of the triggered alert.

       • $pluginName - The short name for the plugin (ex: SNMP).

       • $pluginDescription - The description of the plugin (ex: SNMP Poller).

       • $DIDataResources - The part of SevOne Data Insight report URL for violating resources of the alert. Start the Data Insight report URL with the Data Insight host and report name in URL-encoded format, and append variable $DIDataResources at the end. For example, http://localhost/redirect/v1/reports?reportName=My%20Report&$DIDataResources, where localhost is SevOne Data Insight host and My Report is the Data Insight report name. The URL created, supports Webhooks and emails sent for Alerts.

         Variable $DIDataResources can be used in trigger messages, clear messages, and webhook messages for metric policies.

         To utilize variable $DIDataResources as expected, you must have flag FF_UI_REDIRECT set to true in SevOne Data Insight's /opt/SevOne/chartconfs/di_custom.yaml file. Also, please refer to section SevOne NMS to SevOne Data Insight Drillback URL Configuration Tutorial for details.

         CAUTION

         At present, FF_UI_REDIRECT is an early-access feature flag and is available for limited-use only. Please contact SevOne Support or your Technical Account Manager before you use this flag.

         If /opt/SevOne/chartconfs/di_custom.yaml file does not exist, create it.

         $ ssh sevone@<SevOne Data Insight IP address or hostname>

         Create /opt/SevOne/chartconfs/di_custom.yaml file

         $ touch /opt/SevOne/chartconfs/di_custom.yaml

         Using a text editor of your choice, edit /opt/SevOne/chartconfs/di_custom.yaml file to set the following environment variable and then, save it.

         ui:

         env:

         FF_UI_REDIRECT: true

         Apply the changes made to /opt/SevOne/chartconfs/di_custom.yaml file.

         $ sevone-cli playbook up --tags apps
         Example: Generic URL

         http://<SevOne Data Insight IP address or hostname>/redirect/v1/reports?<enter parameter>&$DIDataResources

         Example# 1: Create URL

         Let's assume the following.

         • SevOne Data Insight IP address or hostname = localhost

         • reportName = Alert Details Report

         Your URL will be,

         http://localhost/redirect/v1/reports?reportName=Alert%Details%Report&$DIDataResources

         Example# 2: Create URL

         Let's assume the following.

         • SevOne Data Insight IP address or hostname = 10.128.10.24

         • reportName = Alert Summary Report

         Your URL will be,

         http://10.128.10.24/redirect/v1/reports?reportName=Alert%Summary%Report&$DIDataResources

         • SevOne Data Insight's datasource name must match SevOne NMS cluster name.

         • When you create a SevOne Data Insight report with variables, it can be used for loading any violating indicator's data.

         • SevOne NMS sends the start time for SevOne Data Insight's report and the report's configured timezone is used for the Epoch start timestamp.

         • When alerts are manually acknowledged from SevOne NMS' user interface, this functionality is not supported as the alerts are cleared manually and not cleared based on condition.

       Flow Policy Variables

       • $flowDeviceId - The Netflow device id of the triggered alert.

       • $flowDeviceName - The Netflow device name of the triggered alert.

       • $flowDeviceIp - The IP address of the Netflow device of the triggered alert.

       • $interface - The index of the netflow interface.

       • $interfaceId - The id of the Netflow interface.

       • $interfaceName - The name of the Netflow interface.

       • $interfaceSystemName - The system name of the Netflow interface.

       • $interfaceDescription - The description for the Netflow interface.

       • $directionId - The id of the Netflow direction.

       • $directionName - The name of the Netflow direction.

       • $filterId - The id of the Netflow filter.

       • $filterName - The name of the Netflow filter.

       • $viewId - The id of the Netflow view.

       • $viewName - The name of the Netflow view.

       • $flowServiceProfileList - The list of Netflow service profile ids.
         

       Trigger Policy (metric and flow) Variables

       The following variables are only supported for metric and flow p olicy alerts.

       • $numTriggeringConditions - The number of triggering conditions.

       • $triggeringConditions - The information and calculated values of the triggering conditions formatted according to the chosen Content-type.

       • $plainTextTriggeringConditions - The information and calculated values of the triggering conditions.

       • $numConditions - The number of all conditions.

       • $allConditions - The information and calculated values of all conditions formatted according to the chosen Content-type.

       • $plainTextAllConditions - The information and calculated values of all conditions.

       Clear Policy (metric and flow) Variables

       • $closureMessage - The closure message for the cleared alert. For example, Acknowledged by for a user acknowledged alert or Alert cleared by clear condition for a system cleared alert.

       
       

       for Definition Type = Trap,

       General Variables

       • $clusterName - The cluster name of the triggered alert.

       • $alertId - The id of the triggered alert.

       • $alertMessage - The message of the alert.

       • $alertType - The origin of the alert. For example, system / flow / trap.

       • $alertState - The severity of the policy. For example, Emergency or Debug.

       • $occurrences - How many times this alert is triggered.

       • $firstSeen - The first time this alert is triggered.

       • $lastSeen - The last time this alert is triggered.

       • $deviceId - The device id of the triggered alert.

       • $deviceIp - The IP address of the device of the triggered alert.

       • $deviceName - The device name of the triggered alert.

       • $deviceAltName - The alternate name of the device that triggered the policy.

       • $trapEventId - The id of the trap event.

       • $trapIPAddress - The IP address of the trap sender.

       • $trapOIDText - The OID of the trap that triggered/clear the alert (OID in textual format).

       • $trapOIDNum - The OID of the trap that triggered/clear the alert (OID in numerical format).

       • $trapVarText - The varbinds and respective values (OID in textual format).

       • $trapVarNum - The varbinds and respective values (OID in numerical format).

       The following variables are not applicable for clear webhooks when the trap alert is acknowledged manually from Events > Alerts.

       • $trapIPAddress

       • $trapOIDText

       • $trapOIDNum

       • $trapVarText

       • $trapVarNum

       Clear Trap Variables

       • $closureMessage - The closure message for the cleared alert. For example, Acknowledged by for a user acknowledged alert or Alert cleared by clear trap for a system cleared alert.

12. To test the definition, click Test Definition button. This populates the result for the user, including the status code, response header, and body.
    

13. Click Save to save and add the new definition.
    

    Example: Webhook Defnition added

    

    
    

Edit Webhook Definition

To edit an existing webhook definition, click on the webhook definition row you want to modify under column Actions. After updating the webhook definition, click Save to save the definition.

Delete Webhook Definition

Test Webhook Definition

To test an existing webhook definition, click on the webhook definition row you want to test under column Actions. You will get a pop-up with the result for the user, including the following details.

• Webhook Definition ID - returns the webhook definition id.

• Webhook Definition Name - returns the webhook definition name.

• Ping Result - r eturns the value of ping test fail or success. If success, it proceeds further.

• Status Code - s tatus code of the webhook request.

• Response - when a webhook request is executed, it returns a response body.

• Response Error - if webhook request fails to execute, it returns a response error.

• Response Header - c ontains all response header values when webhook request has completed.

• Curl Request - c url request has a curl command for every successful request.

Click Close to exit.

Configure Slack Channel

To activate incoming webhooks to post messages from SevOne NMS into Slack, Slack channel must be configured first.

• From a web browser of your choice, enter URL api.slack.com/messaging/webhooks.

• From the left navigation bar, Managing messages > select Using Webhooks.

• Scroll-down and click .

• From Create an app pop-up, click under From scratch.

• In the Name app & choose workspace pop-up,

  • App Name field - enter webhook, for example.

  • Pick a workspace to develop your app in field - choose a Slack Workspace from the drop-down list that you are a member of. For example, SevOne.

  • Click .

    

    Your Slack application is now ready.

• From the left navigation bar, Features > click Incoming Webhooks.

  • Move Activate Incoming Webhooks slider from Off to On.

  • Select button.

  • From the drop-down list, choose a channel. For example, # random. Click Allow.

  • Click Copy to copy the Webhook URL generated for the channel selected in the step above. For example, https://hooks.slack.com/services/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. The request method is POST and the content type is application/json.

    

    Go to the Slack channel you set to receive notifications. For example, SevOne > # random . You will see that you have been notified on Slack.

SevOne NMS to SevOne Data Insight Drillback URL Configuration Tutorial

This section explains the SevOne Data Insight URL structure, how to create the structure from SevOne NMS > Events > Configuration > Webhook Definition Manager, the origin of each of its constituent URL components, and the prerequisites required in SevOne Data Insight and SevOne NMS for this integration to work.