How to automatically send workflow errors as webhooks to a monitoring system

Learn how to automatically send workflow errors as webhooks

Exivity offers the possibility to create notifications for workflows. Users can get notified when a workflow has finished successfully or when it has failed. In some scenarios, you may want to get informed by a Monitoring System about any Failed Workflow alerts. This is possible through webhooks.

What are Webhooks?

Webhooks are automated messages sent from one app to another when something happens.

Continuous Polling

Webhook

In simple words: A webhook URL is provided by the receiving application (in this case, the Monitoring System), and acts like a phone number that the other application (in this case, Exivity) can "call" when an event happens. The data about the event is sent to the webhook URL in either JSON or XML format and it is known as the Payload. As seen in the diagrams above, there is no need to have continuous polling between the Monitoring system and Exivity when using webhooks.

The Monitoring System, receiving the notification through the chosen URL, not only knows an event occurred on another system, but it can also react to it.

How to test your webhooks

In a real case scenario, you would have a webhook endpoint provided by your Monitoring System of choice. For the purpose of this tutorial, we are going to simulate that by using a mock endpoint.

One powerful tool that can get you started with the configuration of a webhook channel is Hookdeck. Hookdeck is a platform that helps you manage your webhooks and create mock endpoints for testing purposes.

All webhook events received through Hookdeck are monitored and readily available to you via the Dashboard or API.

Create a Hookdeck connection

You can easily create your first webhook with their Get Started guide.

During the setting up process, make sure the Destination is configured as a mock endpoint, typically https://mock.hookdeck.com

After you have created your connection, it should look similar to this one:

Example of connection between Exivity and Hookdeck

Create a webhook channel

The next step is to create a notification channel that uses this webhook endpoint. 1. To achieve this, open the Exivity GUI, navigate to the Admin > My notifications menu and select the Channels tab.

2. Provide a Channel name for your channel and select the Channel type as Webhook.

3. Go to your Hookdeck Dashboard and retrieve the URL for the webhook. This URL can be easily found by navigating to the Connections menu, under the Source name:

Copy the Webhook URL

4. Fill in the Webhook URL with the URL provided by Hookdeck:

Creating a Webhook Channel

5. Click the Create button.

Create a workflow notification

Next, create a notification for your workflow and in the Channel section, add the Webhook Channel that you just created.

Also, make sure you fill in a suggestive Name, Title and Description, since you want to identify the Error status easily in your Monitoring System (or in this case, in the Hookdeck events Dashboard):

Example of notification for a workflow that fails

Test case using Hookdeck

Now that you have created a webhook channel and a notification for your workflow using that channel, you can test it to see that your Hookdeck mock endpoint catches your notifications successfully. 1. Ideally, none of your workflows would fail, but for testing purposes, we are going to make one of them fail. Select one of your workflows, and add a faulty step. For example, add an Execute type of step and fill in the following command: ls -la

Obviously, the ls -la command is destined for Linux/Unix operating systems, not for Windows (which is the default OS for your Exivity installation), therefore it is going to fail.

Example of a command that fails in your workflow

2. Click Update to add the new step, then you may also click the Run Now button if you don't want to wait until your Workflow is scheduled to execute.

3. You should immediately see a new event in the Hookdeck events section in the Dashboard:

Hookdeck events for your Connection

The 200 OK status code indicates that the connection between Exivity and Hookdeck was successful, not that the Workflow has not failed.

4. Select the most recent event (which is at the top of the list) and on the right side of your screen, you will see a window containing the Response/Payload in a JSON format. In the body section you can see the message from the notification you created to let you know when your workflow has failed:

The notification message got sent successfully to the Hookdeck endpoint

Analogously, the same steps you have seen in this how-to guide will apply to sending your failed workflow notifications to a Monitoring System, except you will not use the mock endpoint provided by Hookdeck, but the webhook URL provided by your Monitoring System.