Edit

Share via

Create Outgoing Webhooks

  • Article
  • 03/21/2023

The Outgoing Webhook acts as a bot and searches for messages in channels using @mention. It sends notifications to an external web service and responds with rich messages, which include cards and images. It helps to skip the process of creating bots through the Microsoft Bot Framework.

Key features of Outgoing Webhooks

The following table provides the features and description of Outgoing Webhooks:

Features Description
Scoped configuration Webhooks are scoped at the team level. Mandatory setup process for each adds an Outgoing Webhook.
Reactive messaging Users must use @mention for the webhook to receive messages. The users can only message an Outgoing Webhook in public channels and not within the personal or private scope.
Standard HTTP message exchange Responses appear in the same chain as the original request message and can include any Bot Framework message content. For example, rich text, images, cards, and emojis. Although Outgoing Webhooks can use cards, they can't use any card actions except for openURL.
Teams API method support Outgoing Webhooks sends an HTTP POST to a web service and gets a response. They can't access any other APIs, such as retrieve the roster or list of channels in a team.

Create Outgoing Webhooks

Create Outgoing Webhooks and add custom bots to Teams. To create an Outgoing Webhook, follow these steps:

  1. Select Teams from the left pane.

    Screenshot shows the left pane with the Teams icon.

  2. In the Teams page, select the required team to create an Outgoing Webhook and select •••.

  3. Select Manage team from the dropdown menu.

    Screenshot shows the manage Teams option in a Teams channel.

  4. Select Apps on the channel page.

    Screenshot shows the apps tab on a Teams channel.

  5. Under Upload an app, select Create an outgoing webhook.

    Screenshot shows the select create outgoing webhook option.

  6. 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.

  7. Select Create. The Outgoing Webhook is added to the team's channel.

    Screenshot shows the create button in the create an outgoing webhook window.

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.

Note

The Outgoing Webhook is available to the team's users, only if the URL is valid and the server and client authentication tokens are equal. For example, an HMAC handshake.

The following scenario provides the details to add an Outgoing Webhook:

  • Scenario: Push change status notifications on a Teams channel database server to your app.
  • Example: You have a custom app built for your org (LOB app) that tracks all CRUD (create, read, update, and delete) operations. These operations are made to the employee records by Teams channel HR users across a Microsoft 365 tenancy.

Create a method to verify the Outgoing Webhook HMAC token

Using example of inbound message and ID: "contoso" of SigningKeyDictionary of {"contoso", "vqF0En+Z0ucuRTM/01o2GuhMH3hKKk/N2bOmlM31zaA=" }.

Use the value "HMAC 03TCao0i55H1eVKUusZOTZRjtvYTs+mO41mPL+R1e1U=" in the authorization of request header.

To ensure that your service is receiving calls only from actual Teams clients, Teams provides an HMAC code in the HTTP hmac authorization header. Always include the code in your authentication protocol.

Your code must always validate the HMAC signature included in the request as follows:

  • Generate the HMAC token from the request body of the message. There are standard libraries to do this on most platform, such as Crypto for Node.js and Teams webhook sample for C#. Microsoft Teams uses standard SHA256 HMAC cryptography. You must convert the body to a byte array in UTF8.
  • Compute the hash from the byte array of the security token provided by Teams when you registered the Outgoing Webhook in the Teams client. See create an Outgoing Webhook.
  • Convert the hash to a string using UTF-8 encoding.
  • Compare the string value of the generated hash with the value provided in the HTTP request.

Sample code reference

public static AuthResponse Validate(AuthenticationHeaderValue authenticationHeaderValue, string messageContent, string claimedSenderId)
{
    //...
    string providedHmacValue = authenticationHeaderValue.Parameter;
    string calculatedHmacValue = null;
    try
    {
        byte[] serializedPayloadBytes = Encoding.UTF8.GetBytes(messageContent);
 
        byte[] keyBytes = Convert.FromBase64String(signingKey);
        using (HMACSHA256 hmacSHA256 = new HMACSHA256(keyBytes))
        {
            byte[] hashBytes = hmacSHA256.ComputeHash(serializedPayloadBytes);
            calculatedHmacValue = Convert.ToBase64String(hashBytes);
        }
 
        if (string.Equals(providedHmacValue, calculatedHmacValue))
        {
            return new AuthResponse(true, null);
        }
        else
        {
            string errorMessage = string.Format(
                "AuthHeaderValueMismatch. Expected:'{0}' Provided:'{1}'",
                calculatedHmacValue,
                providedHmacValue);
 
            return new AuthResponse(false, errorMessage);
        }
    }
    catch (Exception ex)
    {
        Trace.TraceError("Exception occurred while verifying HMAC on the incoming request. Exception: {0}", ex);
        return new AuthResponse(false, "Exception thrown while verifying MAC on incoming request.");
    }
}

Use Adaptive Cards with Outgoing Webhooks

You can send Adaptive Card, Hero card, and text messages as attachment with an Outgoing Webhook. Cards support formatting. For more information, see format cards with Markdown. Adaptive Card in Outgoing Webhooks supports only openURL card actions.

The following codes are examples of an Adaptive Card response:

Sample code reference


// This method is to read the request body content
string content;
using (var reader = new StreamReader(Request.Body))
    {
        content = await reader.ReadToEndAsync();
    }

var Card = new AdaptiveCard(new AdaptiveSchemaVersion("1.4"))
{
    Body = new List<AdaptiveElement>()
    {
        new AdaptiveTextBlock(){Text= $"Request sent by: {incomingActivity.From.Name}"},
        new AdaptiveImage(){Url=new Uri("https://c.s-microsoft.com/en-us/CMSImages/DesktopContent-04_UPDATED.png?version=43c80870-99dd-7fb1-48c0-59aced085ab6")},
        new AdaptiveTextBlock(){Text="Sample image for Adaptive Card.."}
    }
};

var attachment = new Attachment()
{
    ContentType = AdaptiveCard.ContentType,
    Content = Card
};

var sampleResponseActivity = new Activity
{
    Attachments = new [] { attachment }
};

return sampleResponseActivity;

Code sample

Sample name Description .NET Node.js
Outgoing Webhooks This sample shows how to implement and use outgoing webhook. View View

Step-by-step guide

Follow the step-by-step guide to create Outgoing Webhooks in Teams.

See also

Additional resources

Documentation