Send vROPS notifications using webhooks

Introduction

The way in which you can customize notifications in vROPS has significantly improved in version 8.6. You now have the ability to use payload templates that can include all sorts of vROPS properties. This way you can make your alerts much more meaningful.

When you are using email for notifications however there still is one important caveat. vROPS only allows you to send HTML formatted email. There is no way to use clear text which is problematic when you use email as a means to interact with other systems. For example, when sending notifications to Atlassian’s Opsgenie this makes for some interesting results. The Opsgenie email integration strips all HTML and puts all the readable text on a single line.

Right off the bat when using the default email template, the alert a user receives via Opsgenie does not contain a lot of usable information.

[vRealize Operations Manager] new alert Type:Virtualization/Hypervisor, Sub-Type:Availability, State:critical, Object Type:HostSys

As described before because of the way the HTML formatted email is handled, the description of the alert will contain even more nonsensical information (at least at first glance) because everything is stringed together on a single line. Thankfully Opsgenie supports string processing which you can use to do all sorts of regex magic. But that is still a far cry from what you can achieve with a proper API integration.

Configuring vROPS to send webhook notifications

As it turned out using payload templates is a great way to interact with APIs. Let me explain how I configured my vROPS instance to send notifications to Opsgenie using it’s alert API.

Create an Opsgenie API integration

I won’t go into detail on how to setup an Opsgenie tenant. Atlassian has excellent documentation to help you out with that portion of the setup. But I do want to briefly explain how to setup an API integration. To start with the creation of such an integration first navigate to Teams > [ your team name ] > Integrations. Next, click ‘Add Integration’ and select the API integration. Simply accept all defaults and copy the API key for later use in vROPS.

Outbound settings

Next, return to vROPS to configure outbound settings. You can create an outbound setting instance using the Webhook Notification Plugin when you navigate to Configure > Alerts > Outbound Settings. Next add a new instance, give it a name and other relevant settings for the application you are using. For Opsgenie I only needed to configure the base URL which I set to: https://api.opsgenie.com.

Don’t worry if using the test button raises an error. Most APIs will require some form of authentication and will return an error when it is accessed anonymously.

Payload Templates

With a payload template you can specify exactly what to send to the API endpoint. You can find the payload templates when you navigate to Configure > Alerts > Payload Tempates. Because I needed to create a mapping between the alert criticality within vROPS and the alert priority in Opsgenie I created a payload template for each criticality. When it comes time to create the notifications, I will specify a notification for each criticality as well and make sure to point it to the relevant payload template. You will see how all this ties together in just a minute.

Details

This is where you specify the name, description and the outbound method.

Name	Opsgenie Payload Template: P1 – Critical
Description	Opsgenie payload template which maps vROPS criticality ‘critical’ to Opsgenie priority ‘P1’.
Outbound method	Webhook Notification Plugin

Object Content

I don’t really use this feature. But you can include certain object properties or metrics here. For instance, you could include a host’s maintenance state and include that in your notifications. You can then use that information to prevent a user from being alerted for hosts that have been put into maintenance mode.

Payload Details

By using different payload details for new, updated and canceled alerts you can avoid alert duplication and even close Opsgenie alerts automatically. Settings that are generic for the payload details are as follows:

Do you want to add template input properties?	No
Do you want different payload details for new, updated, and canceled alerts?	Yes

New Alert

This payload is used to create a new alert. Things to notice here are the Opsgenie alias. I populate this property with the vROPS alert id. Which means that any updates with the same alert id received by Opsgenie will be deduplicated. If you already acknowledged the alert this also means no new notifications to the Opsgenie user will be sent out.

Updated Alert

As you can see from the details for updated alerts, I simply treat updates as new alerts. However, because the vROPS alert id is used to create / update the alert these alerts will be deduplicated.

Canceled Alert

When an alert is canceled in vROPS a canced alert notification is sent. Because the vROPS alert id is used in the URL and Opsgenie is told to treat this als the alias just like with the create and update payload details it knows which alert to close.

For the other alert criticalities repeat the process and map immediate with P2, warning with P3 and informational with P5.

Notifications

To configure notifications, navigate to Configure > Alerts > Notifications

Notification

Name	Opsgenie notification for all critical alerts
Description
Notification Status	Enabled

Define criteria

Criticality

Critical

Set Outbound Method

Outbound Method

Webhook Notification Plugin

Opsgenie API

Select Payload Template

Payload Template

Opsgenie Payload Template: P1 – Critical

Just like with the payload templates you can repeat the process to create notifications for the other alert criticalities as well. Although in a production environment you will in all likelyhood be way more selective in which alerts you want to be notified of.

Result

With all the hard work you put in, what is the end result? Well, as you can see the readability of the alert has been greatly improved.

You can see the source actually contains the hostname of the vROPS instance used to send the alert. The entity contains the vROPS resource the alert has been triggered on. And the alias has been populated with the alert id which enables deduplication of alerts. You can actually see on the top left of the screenshot that this alert has been received twice as it is marked with x2.

Finally, the description contiains most of the information found in the default email template. But because each property is on a separate line you can actually read it.

Conclusion

The vROPS payload templates and webhook functionality are a very powerful tool. It took me very little effort to setup and I found it to work quite intuitively.