Create an outgoing webhook

5 minutes

The Outgoing Webhook acts as a bot and searches for messages in channels using @mention. In this unit, you’ll learn how to register an outgoing webhook in a Microsoft Teams channel.

Overview

Users interact with outgoing webhooks in a similar way as they do with bots. Like a bot, users send a message to an outgoing webhook by @mentioning it. Also like bots, outgoing webhooks can respond to messages sent from Microsoft Teams channels with rich messages that can include cards and images.

However, unlike bots, outgoing webhooks are simpler to set up as they don't require registering and configuring the bot via the Microsoft Bot Framework.

Key features

Let's look at some of the key features of outgoing webhooks:

Scoped Configuration: Webhooks are scoped at the team level. You’ll need to go through the setup process for each team you want to add your outgoing webhook to.
Reactive Messaging: Users must use @mention for the webhook to receive messages.
Standard HTTP message exchange: Responses will appear in the same chain as the original request message and can include any Bot Framework message content (rich text, images, cards, and emojis).
Microsoft Teams API method support: Outgoing webhooks send an HTTP POST to a web service and process the web service's response. They can't access any other APIs like retrieve the roster or list of channels in a team.

Outgoing webhooks are scoped to the entire team and are visible to all members of the team. Like a bot, users are required to @mention the name of the outgoing webhook to invoke it in a channel.

Create Outgoing Webhooks

In Microsoft Teams, select Teams from the sidebar:
In the Teams page, select the desired team then select •••.
Select Manage team from the dropdown menu.
Select Apps on the channel page.
Select Create an Outgoing Webhook.
Type the following details in the Create an outgoing webhook page:
- Name: The webhook title and @mention tab.
- Callback URL: The HTTPS endpoint that accepts JSON payloads and receives POST requests from Teams.
- Description: A detailed string that appears in the profile card and the team-level app dashboard.
- Profile picture: An app icon for your webhook, which is optional.
Select Create. The Outgoing Webhook is added to the current team's channel.

A Hash-based Message Authentication Code (HMAC) dialogue appears. It's a security token used to authenticate calls between Teams and the designated outside service. The HMAC security token doesn't expire and is unique for each configuration.

Authenticate messages

Messages sent from Microsoft Teams include the HMAC in the HTTP request's authorization header.

The HMAC is generated by hashing the message with a secret key. Your web service should use the HMAC from the received request to authenticate and verify the message was sent from Microsoft Teams.

Your web service should use the body of the message to generate the HMAC token using the provided security key unique to your outgoing webhook registration. Compare your generated HMAC token to the one included in the request's authorization header value. If they match, you've validated the message was sent from Microsoft Teams.

Respond with success or failure

The last step in your web service is to respond to the Microsoft Teams request message with a success or failure. Outgoing webhook messages sent from Microsoft Teams are sent synchronously and your web service must respond within five seconds. The response from your web service will be added to the same reply chain as the original message. The reply can be a text string, or a rich message that includes images or a card.

Response with an Adaptive Card

You can send an Adaptive Card, Hero card, or text messages as an attachment with an Outgoing Webhook. Cards support formatting. Adaptive Cards in Outgoing Webhooks support only openURL card actions.

The following code demonstrates an Adaptive Card response:

var receivedMsg = JSON.parse(payload);
var responseMsg = JSON.stringify({
    "type": "message",
    "attachments": [
        {
            "contentType": "application/vnd.microsoft.card.adaptive",
            "contentUrl": null,
            "content": {
                "type": "AdaptiveCard",
                "version": "1.4",
                "body": [
                    {
                        "type": "TextBlock",
                        "text": "Request sent by: " + receivedMsg.from.name
                    },
                    {
                        "type": "Image",
                        "url": "https://c.s-microsoft.com/CMSImages/DesktopContent-04_UPDATED.png?version=43c80870-99dd-7fb1-48c0-59aced085ab6"
                    },
                    {
                        "type": "TextBlock",
                        "text": "Sample image for Adaptive Card."
                    }
                ]
            },
            "name": null,
            "thumbnailUrl": null
        }
    ]
});