How to trigger incoming webhooks in Microsoft Teams with Powershell

As a DevOps with work experiences as a Developer and System Engineer, I tend to give for granted that all my colleagues or peers have the same background knowledge or simply the same vocabulary.

But I’ve recently discussed with some seasoned sysadmins working for other companies and I was surprised to discover the barrier was around the vocabulary and the design principles (for developers or system engineers) used as a reference point.

Naturally, we try to solve problems with solutions or technologies that we already used in the past, without exploring all the possibilities. Sometimes we simply don’t get some context or benefits of doing it differently or we can’t measure how expensive can be the adoption of different models or strategies.

For instance: Microservices, RESTfulAPI, Webhooks are common terms that most of us are comfortable using every day, but these design implementations and functions are sometimes not so simple to break it down into small independent pieces.

I’ve also noticed that the most successful articles published on scriptinglibrary.com  have a generic introduction of some fundamental concepts. So feel free to skip this part if you’re already familiar with these topics.

For instance, What is a WEBHOOK?

It’s a very basic and simple concept that once understood could possibly open a whole new world.  It’s a function of an application that via a web request (exactly like a RestAPI) enables the app itself to talk to other applications allowing incoming or outgoing communications.

Frequently, we describe a webhook as a web-callback, in other words, it’s a function that is accessible and passed as an argument to another (maybe external) function and (in general) is executed after.  

What is a RESTFul API?

I guess that every one of us already know what an API is. RESTful APIs play a key role in modern web development and it’s an alternative to a SOAP. They allow web applications to talk to each other over the web which in general exchange data in a JSON (JavaScript Object Notation) format.

What do we mean with MICROSERVICES?

It’s basically breaking down a monolithic app into different independent services. It will increase the complexity of the application, but the abstraction of all individual functions will provide huge benefits in maintaining and developing new features of the web solutions. The individual services will (probably) use RestAPI to communicate with each other.

I hope that with this very simple explanation will clear some of your doubts and will get you to embrace some of the following things.

Chat Software Vs Email

Teams or Slack are in most workplaces widely adopted and are providing every day different ways to getting the things done. It can be very useful especially when working remotely. Most of the modern workflows are less tightly coupled with email systems.  Mail services are still considered a critical service, don’t get me wrong! But whenever possible it’s nice to off-load workflows from mail services.

For this reason, we would like to like to be notified on chat systems whenever some type of event is being triggered so why not interact with chats to trigger events (chat-ops)?

In a recent article (Powershell: Monitoring AD Account Lock-Out Events), I’ve used a desktop notification PowerShell module developed by Josh King called BurntToast.  The requirements were displaying a desktop notification (without sending an email message) whenever a user was locked out.  I’ve soon realized that colleagues were interested to perform exactly the same task, but instead of replicating the same script on different workstations interact with a chat would offer a similar or better experience.

Let’s start with MS Teams (but similar results could be achieved with SLACK).

The first step is configuring an Incoming WEBHOOK, in other words allowing to TEAMS to receive INCOMING messages (in JSON format) over the web so we can use it to tailor it to our needs.

All Microsoft official documentation is really good by the way, these are the instructions to follow: https://docs.microsoft.com/en-us/microsoftteams/platform/concepts/connectors/connectors-using#setting-up-a-custom-incoming-webhook 

Second step. I like to create a channel under my teams for different project or topic, so in this case, I’ve created one called “Test Area for Webhooks”. I’m very creative, I know!

And I’ve uploaded a custom image for a generic user.

Then we can create a custom card or message to be sent with a JSON format as POST request via an HTTP request to the endpoint created on top.

Card Playground

There is also a PLAYGROUND to create cards and play with templates at this link: https://messagecardplayground.azurewebsites.net/

Powershell Script

I’ve decided to use a PowerShell script that will query AD and look for locked-out users. That script is scheduled to run every 5 minutes and includes the JSON template that you can test or customise on the playground and the URI of the webhook to post the message on my “Test Area for Webhooks” channel.

Final Result

This picture below shows the end result. When the event is triggered andthat channel is marked as a favourite I get not only the message but also the notification on every device, and even more importantly the same information is available to the rest of the team. This could be extremely useful if you’re working around in different locations or you travel frequently.

Wrap-Up

The distribution of workloads across on-premises and cloud services will increase the need of integration between them, this is just a basic example, but most modern applications offer integrations or plugins to achieve interoperability and exchange of data and events. Sending a message from PowerShell to Microsoft Teams via a custom incoming webhook is easy and configuring similar integration between SAAS (Software As A Service) is most of the time even more trivial!

If you want to play more with Bots and Chat-Ops, I can suggest you follow the work of Brandon Olin on PoshBot (https://github.com/poshbotio/PoshBot)

I hope you’ve found this article interesting and if you have any question or feedback feel free to contact me, as usual, my code is available on my GitHub repository.