How to automatically send workflow errors as webhooks to a monitoring system
Learn how to automatically send workflow errors as webhooks
Last updated
Learn how to automatically send workflow errors as webhooks
Last updated
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.
Webhooks are automated messages sent from one app to another when something happens.
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.
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.
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:
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:
4. Fill in the Webhook URL with the URL provided by Hookdeck:
5. Click the Create button.
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):
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.
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:
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:
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.
