Using Webhooks to Generate Events

Download this manual as a PDF file

Webhooks enable one system to notify another system about events using a defined message format. You can configure SL1 to receive webhook messages from third-party systems and then generate events from those messages.

Use the following menu options to navigate the SL1 user interface:

  • To view a pop-out list of menu options, click the menu icon ().
  • To view a page containing all the menu options, click the Advanced menu icon ().

This section provides an overview of these features, and it includes the following topics:

What are Webhooks?

Webhooks are system integration patterns where one system notifies other systems about events using a defined message format over HTTP.

In this scenario, the system sending the message is called the provider, and the system ingesting and processing the message is called the receiver.

You can configure your SL1 system to ingest webhooks using one or more webhook receivers. You can then create event policies that will generate events based on the received webhook messages.

Configuring SL1 to Ingest Webhooks

To configure SL1 to ingest webhooks to generate events, you must do the following:

  1. Upgrade to SL1 version 11.2.0 or later.
  2. Enable the webhook collector process.
  3. Configure your Message Collectors to process webhooks.
  4. Add a ScienceLogic Library that contains your webhook handlers, and include that library in an execution environment.
  5. Create a collector group (CUG) and align one or more Message Collectors and devices to that collector group.
  6. Create a webhook receiver.
  7. Define an event policy to create events from webhook payloads.

Enabling the Webhook Collector Process

The "Data Collection: Webhook Collector" system process is disabled by default. Before you can use webhooks to generate events, you must enable this process.

To enable the webhook collector process:

  1. In the classic SL1 user interface, go to the Process Manager page (System > Settings > Processes).
  2. Locate the process named "Data Collection: Webhook Collector" and click its wrench icon (). The Process Editor modal appears.
  3. In the Process Editor modal, complete the following fields:
  • In the Operating State field, select Enabled.
  • In the Appliance Types field, select the Message Collection Unit checkbox.
  1. Click Save.

Configuring Message Collectors for Webhooks

After you have enabled the webhook collector process in the classic SL1 user interface, you must then configure nginx and firewalld on the Message Collectors you want to receive webhooks on so they know which port to listen on for webhook messages.

To configure Message Collectors for webhooks:

  1. Use SSH to access the Message Collector on which you want to receive webhooks.
  2. Run the following command, replacing <port> with the desired port:

sudo /opt/em7/share/scripts/webhook_collector_status.sh -e <port>

The default port for webhooks is 8443. See the section on Required Ports to view a list of ports that are already reserved for use in SL1.

  1. After running the script, check the output to ensure the webhook_collector.service is running. In the output, under "systemd", the webhook_collector.service should show that it is "active (running)". 
  2. If you want to view the webhook collector logs on the Message Collector, you can run the following command:

cat /var/log/em7/webhook_collector.log

Adding a ScienceLogic Library with Webhook Handlers

Before you can create a webhook receiver in SL1, you must add a ScienceLogic library that contains your webhook handlers—Python functions that handle incoming requests. You must then add that library to an execution environment, which enables the Database Server to propagate the library to the Message Collectors using the "Enterprise Database: Collector Config Push" process (config_push.py).

It might be helpful to include a logger in your webhook handler functions so you can view log output.

To add a ScienceLogic library with webhook handlers:

  1. Go to the ScienceLogic Library Manager page (System > Customize > ScienceLogic Libraries).
  2. Click the Actions menu, then select Import ScienceLogic Library. The Import ScienceLogic Library modal appears.
  3. In the modal, click the Browse button.
  4. Select the library file that contains your webhook handlers, and then click Upload.

ScienceLogic libraries support py_directory and py_package .tar format types.

  1. When you are finished, click Import and then click OK to confirm.
  2. After your new library is imported, you must align it to an execution environment. To do so, click the Actions menu and then select Execution Environments. The Execution Environments modal appears.
  3. Click New to create a new execution environment, or select an existing execution environment from the list and click its wrench icon (). The Environment Editor modal appears.
  4. On the Environment Editor modal:
  • If you are creating a new execution environment, type a name for your new environment in the Environment Name field, and then click the save icon ().
  • In the ScienceLogic Library pane, find the Library that you imported and then click its lightning bolt icon () to align the library to the execution environment.
  1. When you are finished, close the Environment Editor modal.

Aligning a Collector Group and Devices for Webhooks

Another step to configuring SL1 to ingest webhooks is to create a collector group (CUG), align the Message Collectors you want to receive webhooks on to that collector group, and assign at least one device to that collector group.

To align a collector group for webhooks:

  1. Create or edit a collector group (CUG) for use with webhooks. When creating the collector group, make sure to do the following: 
  • In the Collector Group Name field, type a unique name for the collector group if you are creating a new collector group.
  • In the Message Collector field, select the Message Collectors on which you want to receive webhooks.

For detailed instructions about creating collector groups, see the section on Creating a Collector Group.

  1. Discover a physical device, create a virtual device, or edit an existing physical or virtual device, and assign that device to the collector group you created in step 1.
  • If discovering a physical device in the current SL1 user interface ("AP2") using guided discovery, select a collector group in the Collector Group Name field on the final page of the guided discovery wizard. For detailed instructions, see the section on Adding Devices Using Guided Discovery.
  • If discovering a physical device in the current SL1 user interface ("AP2") using unguided discovery, select a collector group in the Which collector will discover these devices? field on the final page of the unguided discovery wizard. For detailed instructions, see the section on Adding Devices Using Unguided Discovery.
  • If discovering a physical device in the classic SL1 user interface, select a Data Collector or All-In-One Appliance in the Collection Server PID field on the Discovery Session Editor modal. After initial discovery, each device will use the collector group that contains this Data Collector or All-In-One Appliance for collection and rediscovery. For detailed instructions, see the section on Running a Classic Discovery Session.
  • If creating a virtual device, select a collector group in the Collector field of the Create Virtual Device modal. For detailed instructions, see the section on Defining a Virtual Device.
  • If editing an existing physical or virtual device in the current SL1 user interface ("AP2"), navigate to the Settings tab of the Device Investigator for the device you want to update, click Edit, select a different collector group in the Collection Poller field, and then click Save. For detailed instructions, see the section on The Settings Tab.
  • If editing an existing physical or virtual device in the classic SL1 user interface, navigate to the Device Administration panel for the device you want to update, click its wrench icon (), select a different collector group in the Collection Poller field, and then click Save. For detailed instructions, see the section on Editing Device Settings.

Managing Webhook Receivers

This section describes how to view, create, edit, and delete webhook receivers in SL1.

Viewing the List of Webhook Receivers

You can view a list of webhook receivers on the Webhooks page (Registry > Monitors > Webhooks).

The Webhooks page is accessible only in the classic SL1 user interface.

For each webhook receiver, the Webhooks page displays the following information: 

  • Webhook Name. The unique name for each webhook receiver.
  • Webhook URL Suffix. The unique URL suffix for each webhook receiver.
  • Webhook ID. The unique ID for each webhook receiver.
  • Import Module. The Python handler module that is imported from the ScienceLogic Library associated with each webhook receiver.
  • Import Handler. The Python handler function that is imported from the ScienceLogic Library associated with each webhook receiver.
  • Status. The status of each webhook receiver.
  • Device ID. The unique ID of the device aligned to each webhook receiver.
  • Device Name. The name of the device aligned to each webhook receiver.
  • IP Address. The IP address of the device aligned to each webhook receiver.
  • Device Category. The category assigned to the device aligned to each webhook receiver.
  • Organization. The organization assigned to the device aligned to each webhook receiver.

Creating a Webhook Receiver

To create a webhook receiver:

  1. Go to the Webhooks page (Registry > Monitors > Webhooks).

The Webhooks page is accessible only in the classic SL1 user interface.

  1. Click the Create button. The Create New Webhook modal appears.
  2. On the Create New Webhook modal, select the device that you want to align to the new webhook receiver by clicking its device icon ().
  3. On the Create New Webhook modal, select the ScienceLogic Library that contains the webhook handler function by clicking its library icon ().
  4. On the Create New Webhook modal, complete the following fields:
  • Device. Displays the device that you selected to align to the webhook receiver. Click Change Selected Device to select a different device.
  • Webhook Name. Type a unique name for the webhook receiver.
  • Webhook URL Suffix. Type a unique URL suffix for the webhook receiver.
  • Available Webhook URL. Displays the auto-generated full URL of the webhook receiver. The webhook URL consists of the IP address and port number of the Message Collector that is associated with the selected device's collector group, the static URL fragment "/api/v1/webhook", and the webhook URL suffix, in the following format:

https://<IP address>:<port number>/api/v1/webhook/<webhook URL suffix>

 

For example: https://10.2.20.56:8888/api/v1/webhook/test_webhook_url

For SL1 to auto-generate the full webhook URL, you must have already set up and enabled the webhook collector service on the associated Message Collector.

If the selected device is aligned to a collector group that includes multiple Message Collectors, then multiple URLs will appear in this field, as SL1 will auto-generate a URL for each Message Collector.

  • Library. Displays the ScienceLogic Library that you selected to align to the webhook receiver. Click Change Selected Library to select a different ScienceLogic Library.
  • Import Module. Type the Python handler module that you want to import from the selected ScienceLogic Library. The Python handler module consists of the name of the selected ScienceLogic Library as it appears in the Library field above, followed by the handler module name, separated by a period, in the following format: 

<Library name>.<handler module name>

 

For example: webhook_handler_libary.example_handlers

  • Import Handler. Type the name of the Python handler function that you want to import from the selected ScienceLogic Library.
  1. Click Save.

To test that the webhook receiver is working, you can send an example test request by running the following command through the terminal, and then checking the log /var/log/em7/webhook_collector.log to view the results:

curl -XPOST -k <webhook_url> -d {} -H 'Content-Type: application/json' -vvv

Editing and Deleting Webhook Receivers

You can edit and delete existing webhook receivers from the Webhooks page (Registry > Monitors > Webhooks).

To edit a webhook receiver:

  1. Go to the Webhooks page (Registry > Monitors > Webhooks).

The Webhooks page is accessible only in the classic SL1 user interface.

  1. Locate the webhook receiver that you want to edit and click its wrench icon (). The Editing Webhook modal appears.
  2. In the Editing Webhook modal, change the values in one or more fields.
  3. Click Save to save your changes.

To delete a webhook receiver: 

  1. Go to the Webhooks page (Registry > Monitors > Webhooks).

The Webhooks page is accessible only in the classic SL1 user interface.

  1. Locate the webhook receiver that you want to delete and then click its checkbox to select it.
  2. Select Delete Webhooks from the Select Action drop-down menu.
  3. Click the Go button.

Generating Events from Webhooks

For SL1 to generate events from ingested webhook messages, you must create an event policy that looks for API messages that match strings from the webhook message.

To create an event policy for webhooks, follow the steps in the section Defining an Event Policy. When creating the policy, make sure to do the following: 

  • In the Event Source field, select API.
  • In the Match String fields, type the string(s) you want to match from the webhook payload.

If configured correctly, events from webhook messages will appear on the Event Console page, as well as in device logs.