Creating Generic Webhook integrations

Before you begin

To configure a generic webhook integration, you need the following information for the application that you are connecting to IBM Cloud Pak for AIOps:

• A name and description for the webhook integration.
• If you need to secure the webhook, the appropriate user name and password.
• The JSONata that maps the incoming JSON payload to IBM Cloud Pak for AIOps events.

Creating a Generic Webhook integration

To create a Generic Webhook integration, complete the following steps:

1. Log in to IBM Cloud Pak for AIOps console.

2. Expand the navigation menu (four horizontal bars), then click Define > Integrations.

3. On the Integrations page, click Add integration.

4. From the list of available integrations, find and click the Generic Webhook tile.

   Note: If you do not immediately see the integration that you want to create, you can filter the tiles by type of integration. Click the type of integration that you want in the Category section (Events).

5. On the side-panel, review the instructions and when ready to continue, click Get started.

6. On the Add integration page, define the general integration details:

   • Name: The display name of your integration. You cannot use spaces or special characters in the display name. Use only alphanumeric characters.

   • Description: An optional description for the integration.

   • Authentication type: Select the Username/Password or None option.

   • Username: Enter the appropriate username to authenticate the connection.

   • Password: Enter the appropriate password to authenticate the connection.

   • Webhook route: The predefined full URL (location) of the webhook. This field is not editable.

   • Maximum event rate: The maximum number of events (per second) that are allowed by the Generic Webhook integration. You must specify a value between 10 and 1000 events per second. The default is 100.
     Note: The actual rate that events are collected depends on network performance.

7. Click Next.

8. Configure the event mapping.

   Use JSONATA to map the incoming JSON payload to the IBM Cloud Pak for AIOps event data schema. You can start from scratch or load an example mapping. The mapping configuration will be tested to ensure that it is in a valid JSONata format.

   Click Load sample mapping to show a selection of available samples and select an appropriate use case to load. For example, you can select SevOne or Turbonomics. Finish the mapping by clicking the Load sample mapping button.

   

   The following mapping is an example mapping for an integration with IBM SevOne Network Management System (NMS)

   (
       {
           "severity": alertState="Alert"?6:alertState="Emergency"?6:alertState="Critical"?6:alertState="Error"?5:alertState="Warning"?3:alertState="Notice"?2:alertState="Info"?2:alertState="Debug"?2:1,
           "summary": description,
           "resource": {
               "name": deviceName
           },
           "type": {
               "classification": policyName,
               "eventType":  alertState = "Cleared" ? "resolution" : "problem"
           },
           "sender": {
               "name": "IBM SevOne Network Management System",
               "type": "Webhook Integration"
           },
           "expirySeconds": alertId="-1"?300
       }
   )
   

   Note: The JSONata expression must contain the summary, resource and type fields. If the fields are missing, the event is invalid and might be rejected. Values mapped to the classification field in the data model are especially significant. Inappropriate values assigned to this field at the time of mapping has a negative impact on several downstream activities, such as Golden Signal classification, incident creation, and recommended policies. Classification should contain information summarizing the event type, for example, CPU Utilization, Node Down, or the actual metric name itself.

   Review the following topics for more example mappings to help you configure your own mappings:

   • Example: IBM SevOne Network Management System (NMS) generic webhook event mappings
   • Example: Prometheus AlertManager (Red Hat OpenShift) generic webhook event mappings

9. Enable the webhook. Click the toggle to change the setting Enable webhook or Disable webhook. When disabled, the webhook integration discards incoming HTTP requests.

10. Click Done.

11. Within the application that you are connecting to IBM Cloud Pak for AIOps, complete any required configurations to support the integration.

    Important: You might need to configure a signed trusted certificate for IBM Cloud Pak for AIOps that the external system that you are connecting to trusts. When an external system is sending a payload through this webhook integration, the payload goes through a TLS handshake. If IBM Cloud Pak for AIOps is using the default configuration, IBM Cloud Pak for AIOps uses self-signed certificates that an external system will not accept if the system does not trust self-signed certificates. To configure a signed trusted certificate, If you are connecting to a SaaS system, you might need to use an internationally recognised certificate authority certificate as you might need be able to update the SaaS trusted certificate authority list. Otherwise, you can use your own certificate authority and add the certificate to the external system.

    For example, to connect to IBM SevOne Network Management System (NMS) you need to complete the following tasks:

    • Copy the Webhook URL from IBM Cloud Pak for AIOps.

    • Importing a CA signer certificate into IBM SevOne Network Management System (NMS).

    • Add the webhook destination within IBM SevOne Network Management System (NMS).

      In the IBM SevOne Network Management System (NMS) UI go to Events > Configuration > Policy Browser > Configure webhook destination > Add webhook destination.

    • Add the webhook into existing policies to send event data to IBM Cloud Pak for AIOps.

12. Test your integration with your connected application to verify that events are sent to IBM Cloud Pak for AIOps, and display as alerts in the Alert Viewer of the IBM Cloud Pak for AIOps UI.

Enabling or disabling a Generic Webhook integration

After you create your webhook integration, you can enable or disable the webhook by completing the following steps:

1. Log in to IBM Cloud Pak for AIOps console.

2. Expand the navigation menu (four horizontal bars), then click Define > Integrations.

3. Click the Generic Webhook integration type on the Manage integrations tab of the Integrations page.

4. On the Generic Webhook page, click the name of the integration that you want to edit. Alternatively, you can click the options menu (three vertical dots) for the integration and click Edit. The integration configuration opens.

5. Enable or disable the webhook by clicking the toggle to change the setting to Enable webhook or Disable webhook. When disabled, the webhook integration discards incoming HTTP requests.

6. Click Save when you are done.

Your webhook is now enabled or disabled.

Editing a Generic Webhook integration

After you create your integration, you can edit the integration. For example, if you want to add or change the listed GUI or backend URLs for the IBM Tivoli Netcool/Impact endpoint, or to update the User ID or password. To edit a integration, complete the following steps:

1. Log in to IBM Cloud Pak for AIOps console.

2. Expand the navigation menu (four horizontal bars), then click Define > Integrations.

3. Click the Generic Webhook integration type on the Manage integrations tab of the Integrations page.

4. On the Generic Webhook page, click the name of the integration that you want to edit. Alternatively, you can click the options menu (three vertical dots) for the integration and click Edit. The integration configuration opens.

5. Edit your integration as required. Click Save when you are done editing.

Your integration is now edited.

Deleting a Generic Webhook integration

If you no longer need your integration and want to delete it entirely, you can delete the integration from the console.

To delete a integration, complete the following steps:

1. Log in to IBM Cloud Pak for AIOps console.

2. Expand the navigation menu (four horizontal bars), then click Define > Integrations.

3. Click the Generic Webhook integration type on the Manage integrations tab of the Integrations page.

4. On the Generic Webhook integrations page, click the Delete icon for the integration that you want to delete.

5. Enter the name of the integration to confirm that you want to delete your integration. Then, click Delete.

Your integration is deleted.