Using Webhooks as Follow-Up Action
In this article, we will introduce you webhooks, which is a new Follow-up Action introduced in ControlUp version 8.6.5. Webhooks, as part of ControlUp's Trigger feature, provide a way to send real-time notifications to an external system once an incident trigger is triggered.
What is a Webhook?
A webhook is a user-defined HTTP callback that you can use to push information or notifications to a configured URL via an HTTP POST call. For example, imagine you need to notify users in a Slack group if one of your production machines reaches a critical Stress Level. Webhooks can be used in a number of situations where they prove useful. In this example, we will create a Machine Stress Level trigger that, when activated, will send a message to a Slack channel with machine information.
To follow the instructions in this article, you need to meet the following prerequisites:
- ControlUp version 8.6.5 or later
- At least one ControlUp Monitor installed. This is a general prerequisite for using triggers. Additionally, monitors need internet connectivity to reach the API endpoint.
- A ControlUp license with activated Automated Actions. You can check if your license includes the Automated Actions feature in the Home ribbon of the Real-Time Console > Help > About > Licensing.
Step 1 - Get your Webhook Provider Ready
Before you begin configuring a trigger in your ControlUp environment, make sure that you completed the setup of the webhook for the API provider. We will use the Slack API, click here and follow the instructions to set up and configure a webhook in Slack.
You can use the webhook Follow-up Action with other webhook receivers, such as GitHub, Dropbox or Zendesk.
Step 2 - Optional: Send Test Message
After setting up your service endpoint, you can send test messages from the monitor machine by using an API testing tool of your choice. By testing messages, you can verify outbound and inbound traffic to/from the service endpoint. Add the URI, create a test message in JSON format and send the HTTP PUT request, as shown in the screenshot below.
Later, you will see how to test messages within the Real-Time Console. For now, if you received a 200 OK status code, then your service URI is ready to be used.
Step 3 - Create a Trigger
We start by creating a new trigger. In the Home ribbon of the Real-Time Console, click Triggers to see all triggers in your ControlUp environment.
In our example, we want to define a trigger that monitors the Stress Level of machines in our data center and if the Stress Level reaches the critical level for at least 3 consecutive seconds, we want to send a user-defined message via a webhook to a Slack group.
To create a new trigger with a webhook follow-up action
- In the Trigger Settings window, click + Add Trigger...
- Select a trigger. For our example, we use the Stress Level trigger. Click Next to configure the trigger conditions.
- The Stress Level trigger requires a Record Type, Stress Level, and Duration. In this case, we are checking whether a machine has reached a critical state for at least three consecutive seconds. Click Next to add filter criteria.
- Click Filter editor... and add the machine hostname by clicking New Item and choose Name from the drop-down menu. At the bottom, define for which machines the trigger should be applied. In our case, we use an asterix (*) to apply the filter on all machines.
- Confirm the filter criteria by clicking Next. Select which ControlUp extensions or folders the trigger should be applied to. We know our machine is located in the IL Datacenter folder, so we select it and keep the Schedule All days. Click Next to configure the Follow-up Action.
- In this step, we want to add a webhook as a Follow-up Action. Click Add and select Send a RESTful API request from the Type drop-down menu. A window for configuring the webhook is displayed.
- When invoking a webhook, you can use different HTTP methods, such as GET, PUT, DELETE and POST. In our example, we want to POST an HTTP request to the API endpoint of our Slack application (URI).
- By default, no template is selected so we need to add a new template or configure a new one. From the Template drop-down list, select Add new template to create a new template with Trigger variables that you can use in the HTTP header, body or in the URI of the API endpoint. To learn more about templates and the use of Trigger variables, click here.
- To keep things simple, we define a message displaying a single line of text that informs the Slack channel about a machine that reached the critical Stress Level. Click OK to save the template configuration. Click again OK to apply the template to the webhook.
- You can add more Follow-up Actions to your trigger. After adding the new trigger, verify that the message is sent correctly. Click Edit... to see the webhook configuration.
- The new template is automatically selected. Click the Test button to send the template. The HTTP code indicates whether the message was sent successfully. Click OK to close the window and click Finish to save the trigger settings.
- In the Trigger Settings window, make sure that the Enabled checkbox is selected. The trigger name appears with an asterix and in bold text if the trigger hasn't been saved yet. In this case, click Apply and then OK.
- As shown in the screenshot below, if one of the machines reaches a critical Stress Level, a message is sent to the Slack group.
In this article, you learned how to use webhooks as a new Follow-up Action in your incident triggers to send notifications to a third-party API provider.