In this second part of the series on Webhooks, we further expand our knowledge on Webhooks by understanding how an outgoing Webhook triggered by an entity, can be captured by a third-party application. In the last post, we already learned what Webhooks are and how they can be used to facilitate real-time communication between multiple entities. If you have not checked that out yet then I would highly recommend to do so first because all subsequent parts of this explainer series are based on the fundamentals we covered in the first introductory post.
For this demo, we will use one of the most popular Enterprise messaging platforms – Microsoft Teams & see how a message dropped in a MS Teams channel triggers an outgoing webhook. If you want to see how Webhooks can be used with other platforms like Webex then feel free to drop a comment and I’ll write a separate post for that.
The table of contents is listed below. You can click on the links directly to jump to the relevant section.
- ngrok – What & Why
- ngrok – Configure & Monitor
- Webhook – MS Teams Message Flow
- Configuring an Outgoing Webhook in MS-Teams
- Testing the Webhook
ngrok – What & Why
As we had covered in the introductory blog post, a Webhook is basically nothing but an event that triggers an HTTP POST request. If we are working with publicly accessible SaaS platforms like MS Teams or Cisco Webex then it’s natural for us to provide a URL that can receive the incoming POST request from such platforms. If the recipient application is already hosted on the internet then it greatly simplifies the process. We can use that application’s public URL to receive the incoming POST request & process the data accordingly. However, if we have a local application which is confined within the boundaries of the enterprise network then we need some way to establish a web link between this local application & the SaaS platform hosted on the internet. That’s where applications like ngrok come in.
Without getting too much into detail, ngrok basically creates a secure tunnel to the localhost machine. It provides a publicly accessible URL which can help us expose our local development server to the internet without having to bother about hosting our application on the internet. This enables us to keep developing our application on the local machine and use the ngrok tunnel to make this “local” application accessible on the internet. This is just for demonstration purposes and should be used only during the dev/test phase. You can download ngrok from the following website
ngrok – Configure & Monitor
The configuration of ngrok involves following steps
- Open the command prompt and navigate to the directory where ngrok is installed
- Then issue the command ngrok http 5000 or any port for that matter and hit Enter.
- The tunnel will start and the line item you need to pay attention to is “Forwarding“. It shows that “https://46d4-2604-3d08-987c-5100-f4d0-7ee0-8cdb-16f5.ngrok-free.app” is being forwarded to our local machine at “http://localhost:5000“. This means that whatever traffic comes to the “Public HTTPS” URL given above will be diverted to the localhost.
- Another line item you need to make a note of is “Web Interface”. This is where you will see the Webhook notification details. You will see the following page when you navigate to the address mentioned in the “Web Interface” line item. We will come back to this page again towards the later part of this tutorial.
Webhook – MS Teams Message Flow
The end-to-end Webhook message flow is supposed to follow the path highlighted in the diagram given below.
- A user sends a message in the MS Teams client app.
- That message is received by the M365 Cloud service and a subsequent Webhook is triggered.
- This Webhook involves sending an HTTP POST message to the third party application which is accessible by M365 service over the internet.
Configuring an Outgoing Webhook in MS-Teams
- Open MS Teams desktop client
- Select the Team which needs to be configured for Webhook and go to Manage Team option
- Go to the “Apps” tab and click on “Create an Outgoing Webhook”.
- Fill the following details and click on Create
- Name : Give it a recognizable name
- Callback URL : This is the publicly accessible URL of your application. For this demo, this will be the URL from ngrok.
- Description : Provide an appropriate description.
- Profile Picture : Assign any specific picture if you want.
Once it’s created, you will be provided with a “Security Token” value. You will need this token later when you decide to integrate your custom application with the Teams client.
Testing the Webhook
In order to test the Outgoing Webhook, you will just need to send a chat message on any channel in the Team for which the above Outgoing Webhook was created. In the below screenshot, I have a channel called “Internal Testing” where I will send a message and that, in turn, is supposed to trigger the Webhook to the publicly accessible ngrok URL.
As can be seen in the below screenshot, I first referenced the “Webhook” we created earlier by its name followed by a simple message in the channel. Please ignore the “Sorry, there was a problem encountered with your request” message for now.
The following is what showed up on the ngrok side. It received the incoming POST request from Microsoft which was triggered as a result of the message I had sent in the channel earlier. This output is in JSON format which can be utilized and manipulated further by our custom application if there is a need for it.
The reason why we see the “502 Bad Gateway” message and those “Sorry, there was a problem encountered with your request” messages in response to our chat message is because we do not have an actual application to receive and process the incoming POST request from Microsoft. The only thing ngrok is doing is basically managing a “tunnel” that is receiving the POST request on the publicly accessible URL and passing it on to the “localhost” interface. But there is nothing actually running on the local interface. It’s just acting as an anchor to receive the forwarded data from public URL. If we had an actual application that is running on our local computer and using port 5000 then we would’ve had the capability to do something with the JSON data received by ngrok’s public URL. And that would not have resulted in the “502 Bad Gateway” error.
I hope this post was helpful in making you more comfortable & familiar with the inner workings of Webhooks & their practical usage. The increased focus on Webhooks in the recent years can be attributed to the speed at which organizations are adapting SaaS platforms like Webex and MS Teams. It’s only going to get bigger with each passing day and therefore, it is imperative that we all understand how these things work and how they can be adapted to solve real world use cases. In upcoming posts, I’ll be going over other flavors of Webhooks before finally concluding it with a practical use case. So, stay tuned!!
Please feel free to drop your feedback/suggestions, if any. Until then, Happy Learnings!!
Learn UC Collaboration 