Creating Generic Webhook connections

Before you begin

To configure a generic webhook connection, 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 connection.
• 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 connection

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

1. Log in to IBM Cloud Pak Automation console.

2. Expand the navigation menu (four horizontal bars), then click Define > Data and tool connections.

3. On the Data and tool connections page, click Add connection.

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

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

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

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

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

   • Description: An optional description for the connection.

   • 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.

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.

   The following mapping is an example mapping for a connection 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 Connector"
           },
           "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. The connector assigns the following default values to the event data:

   • "summary":"Unknown event."
   • "resource":{"name":"Unknown"}
   • "type":{"eventType":"problem","classification":null,"condition":null}

   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 connector 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 connection.

    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 connection, 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 connection 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 connection

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

1. Log in to IBM Cloud Pak Automation console.

2. Expand the navigation menu (four horizontal bars), then click Define > Data and tool connections.

3. Click the Generic Webhook connection type on the Manage connections tab of the Data and tool connections page.

4. On the Generic Webhook page, click the name of the connection that you want to edit. Alternatively, you can click the options menu (three vertical dots) for the connection and click Edit. The connection 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 connector discards incoming HTTP requests.

6. Click Save when you are done.

Your webhook is now enabled or disabled.

Editing a Generic Webhook connection

After you create your connection, you can edit the connection. 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 connection, complete the following steps:

1. Log in to IBM Cloud Pak Automation console.

2. Expand the navigation menu (four horizontal bars), then click Define > Data and tool connections.

3. Click the Generic Webhook connection type on the Manage connections tab of the Data and tool connections page.

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

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

Your connection is now edited.

Deleting a Generic Webhook connection

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

To delete a connection, complete the following steps:

1. Log in to IBM Cloud Pak Automation console.

2. Expand the navigation menu (four horizontal bars), then click Define > Data and tool connections.

3. Click the Generic Webhook connection type on the Manage connections tab of the Data and tool connections page.

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

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

Your connection is deleted.