New URL Format for Incoming Webhook Used by Teams and Groups

Connectors Must be Updated by April 11, 2021

Office 365 Notification MC234048 published on January 12 announces that Microsoft is improving the security of the “Microsoft Teams connector apps webhook.” That mouthful refers to the incoming webhook connector which can be attached to Microsoft 365 Groups or Teams channels to allow the posting of cards generated from information in network sources.

The webhook is a unique URL which applications use to address the channel where they wish to publish information. The change being made adds the tenant name to the webhook URL to make it more apparent than previous. According to Microsoft, security is improved through the presence of the tenant name because organizations can then use the information to filter traffic logs. Quite how this improves security is beyond me because the tenant identifier (a GUID) has always been present in the webhook URL.

The changeover to the new format started on January 11, 2021. Old format webhooks will continue working for three months. The webhooks must be updated to the new format by April 11, 2021 to ensure that information continues to flow.

Interpreting the Webhook URL

The new format webhook looks like this:

https://office365itpros.webhook.office.com/webhookb2/7aa49aa6-7840-443d-806c-08ebe8f59966@c662313f-14fc-43a2-9a7a-d2e27f4f3478/IncomingWebhook/8592f62b50cf41b9b93ba0c0a00a0b88/eff4cd58-1bb8-4899-94de-795f656b4a18

The component parts are of the webhook are:

• Tenant name (taken from Azure AD): Office365itpros. This is the new piece added to the webhook URL.
• Webhook root: webhook.office.com/webhookb2. Old webhook URLs use office.com/webhook.
• Group identifier: The Azure AD identifier for the Microsoft 365 group. In the example, this is 7aa49aa6-7840-443d-806c-08ebe8f59966.
• Tenant identifier: The Azure AD identifier for the tenant. In the example, this is c662313f-14fc-43a2-9a7a-d2e27f4f3478. The group and tenant identifiers are separated by an at sign.
• Provider name: This is always “IncomingWebhook.”
• Alternate identifier: Another GUID to make the URL unique because a group or channel can support multiple webhooks. In this case, it’s 8592f62b50cf41b9b93ba0c0a00a0b88.
• Group owner: The Azure AD identifier (GUID) for the group owner. Or rather, the account of the owner who adds the webhook to the group.

The same connector is used to bring data in from external sources to both Teams (data is posted in a channel) and Microsoft 365 Groups (data is posted as topics in email conversations).

Updating a Connector

Updating a connector to use the new format webhook isn’t hard. The trick is to know where the connectors are currently configured. When you know that, a group owner can access the set of connectors and check the incoming webhook connector. If “Attention required” appears for the connector, the webhook must be updated (Figure 1). If not, the connector is using the new format.

Clicking Manage brings you to the connector settings (Figure 2). Click Update URL to generate a new format webhook URL and then Save to update the connector. Before you save, make sure that you copy the webhook URL as you’ll need this to update the applications which send data to Microsoft 365 Groups or Teams through the connector.

The applications might be as simple as a PowerShell script (here’s an example of posting Microsoft 365 roadmap items to Teams and another to post notifications about inactive mailboxes). In other cases, the webhook URL might be used to post information coming from an application.

Finding Teams Using the Incoming Webhook

If you have only a few teams configured with the incoming webhook it won’t be hard to find and update the URL. Things are a little more complex in large organizations where many webhooks might be in use for both Teams and Microsoft 365 Groups. In these circumstances, some help might be needed to find all the connectors.

Some time ago, I wrote a PowerShell script to show how to report the channels and tabs connected to Teams. The point of that post was to demonstrate the retrieval of large amounts of data from Teams. As each team has standard apps (like Calls)), can have up to 200 channels, and each channel can have multiple tabs (including standard tabs), the script collects a bunch of information. In this instance, we can use it to find which teams have connectors configured with the incoming webhook connector.

After running the script, we can query the output report to find instances of teams with the connector:

$Report | ?{$_.App -eq "incoming webhook"} | Format-Table Team

Team
----
Technology News and Views
Engineering Colleagues
Human Resources Group
PL Test
Industry News

The report doesn’t tell us for which channel the connector is configured, but that should be easily found.

In passing, if you want to get an insight into the number of standard apps installed by Teams, run this command to group the results in the report:

$Report | Group App | Sort Count -Descending | Format-Table Name, Count

As they say, the output is “interesting”!

---

Interpreting the real meaning of a Microsoft announcement takes experience and background knowledge. Learn from the best by subscribing to the Office 365 for IT Pros eBook. No bumpf, just knowledge.