Introducing WebHook support for OMS Alerts

Summary: Learn about cool integration with Slack and other tools by using Operations Management Suite (OMS) WebHook support for OMS Alerts.

Good morning everyone, Alexander Frankel here, and today I want to talk about WebHook support for OMS Alerts.

Since we released OMS Alerting in December, we’ve seen a fantastic amount of active usage of the feature -- and some complex querying to go with it! It’s been great working with all of you and gathering feedback about what’s been working well and what needs improvement.

We’ve also gotten great help from our community. Here are some really useful articles from some of our MVPs and partners:

Currently, we are in the midst of acting on all that great feedback. Over the next few weeks, you’ll be seeing a steady rollout of new capabilities -- starting today with WebHook support for OMS Alerts.

What is a WebHook?

A WebHook is just an HTTP callback URL. When an alert fires, you can choose to send the alert to a URL of your choosing. Many services create unique URLs to talk to a specific part of the product -- like a Slack channel or an incident management table. In the same way that a REST API became a standard way for you to talk to applications, a WebHook is becoming the standard way for applications to talk to you when an event occurs.

Why do I want to use WebHooks with OMS?

Great question! With WebHooks you can do things like send a message to Slack, raise an incident in an ITSM tool, or integrate with your own custom tool. In short, you want to use WebHooks with OMS because it’s going to make integrating into your existing workflow really easy -- no code required! I’ll run you through the basics of how to use WebHooks, as well as an example of sending the details of the alert to a Slack channel.

To use a WebHook, you need to provide one mandatory field, WebHook URL, and one optional field, custom JSON payload.

  • WebHook URL: This is the destination URL you want to be called when the alert fires (for example, a Slack channel). Many services supply WebHooks in different ways. In many cases, even if services don’t support WebHooks directly, you can still use their public APIs. Just provide any authentication or other required fields in the custom JSON payload.

Screenshot of the "WebHook URL" field.

  • Custom JSON payload: This optional field lets you add more data when we send the alert to your destination. Sometimes you will need to use this field to include authentication tokens, incident IDs, etc. Just use JSON formatted text.

Screenshot of the optional "custom JSON payload" field.

OK, I’m totally sold on WebHooks. Can you show me how to send a message to Slack?

Yep.

In this example, I’m going to alert when I have too many event log errors in my environment. So I’ll execute the following query:

Type=Event EventLevelName=error

  1. Configure your alert.

    If you haven’t already, enable the Alerting preview by going to Settings > Preview Features.

    I’m not going to go through all the details of how to set up an alert. For that, you can check out my post from December, but here’s my configuration:

    • • Check for this alert every 5 minutes
    • • When the number of results is greater than 100
    • • Over a 60 minute time window

     

  2. Copy the WebHook URL from Slack.

    Each service is going to have its own method of generating a WebHook. I’ll show you where to find it in Slack. This is all assuming you already have a Slack account.

    To start, click the drop-down for the channel you want to send a message to.

    Screenshot of Slack that shows how to find a channel you want to send a message to.

    In the App Directory, search for WebHooks, and select Incoming WebHooks.

    Screenshot of "Incoming WebHooks" in the App Directory.

    Select Install next to your team name (because I’ve already set this up, my screen says Configure). Select Add Configuration, choose the channel you’d like to send the message to, and select Add incoming WebHooks integration. Copy this WebHook URL, which we will paste into our alert configuration.

    Screenshot of configured WebHook integration for a team.

    Screenshot of the "WebHook URL" field in the alert configuration.

  3. Add the WebHook URL to the OMS alert. Simply paste this URL into the WebHook URL field in the alert creation pane.

    Screenshot of the "WebHook URL" field with the URL that you pasted.

  4. Add a custom JSON payload to match what Slack is expecting.

    Here’s where WebHook support gets really powerful. We are going to add some JSON formatted data to be sent with the alert. These fields are going to match what Slack is expecting. Here’s a really simple example of what you can add to this payload to send a simple message to Slack:

    {"text":"#alertrulename fired with #searchresultcount results exceeding the threshold of #thresholdvalue"}

    Now just add this to the custom JSON payload field, and select Save.

    Screenshot of the "custom JSON payload" field with JSON formatted data.

    Here’s what this would look like in Slack:

    Screenshot of Slack result for the custom JSON payload that you created.

    You’ll notice we use the ‘#’ symbol to add properties of the alert like the “name”, “threshold”, and “result count” to the message being sent. You can view the full list of "#" parameters.Slack allows for lots of customization of this payload. You can read all about it in the Slack API documentation. This is the payload we’ve been using within our dev team:

    {

    "attachments": [

    {

    "title":"OMS Alerts Custom Payload",

    "fields": [

    {

    "title": "Alert Rule Name",

    "value": "#alertrulename"

    },

    {

    "title": "Link To SearchResults",

    "value": "<#linktosearchresults|OMS Search Results>"

    },

    {

    "title": "Search Interval",

    "value": "#searchinterval"

    },

    {

    "title": "Threshold Operator",

    "value": "#thresholdoperator"

    },

    {

    "title": "Threshold Value",

    "value": "#thresholdvalue"

    }

    ],

    "color": "#F35A00"

    }

    ]

    }

    The payload corresponds to the following message in Slack:

    Screenshot of results of custom payload in Slack.

     

 

That was super detailed and helpful. Where else can I use WebHooks?

Pretty much anywhere! Some services will explicitly support WebHooks in a variety of ways. Even if your product doesn’t have WebHook support, in many cases you can just leverage that product’s API. Typically, that just means including some important parameters in your custom JSON payload field.

With WebHook support for OMS, we are laying the foundation to use OMS as a platform that can easily be integrated into your existing workflow. We will continue to add functionality to WebHooks, as we see this as a key tool for powerful integration scenarios -- both into and out of OMS.

As always, let us know what you think in the comments here, or feel free to email me directly at alfran@microsoft.com. We’re looking forward to seeing what you can do!

That is all I have for you today.

I invite you to follow me on Twitter and the Microsoft OMS Facebook site. If you want to learn more about Windows PowerShell, visit the Hey, Scripting Guy Blog. If you have any questions, send email to me at scripter@microsoft.com. I wish you a wonderful day, and I’ll see you tomorrow.

Alexander Frankel

Microsoft Operations Management Team