Create Outgoing Webhook

The Outgoing Webhook acts as a bot and search for messages in channels using @mention. It sends notifications to external web services 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 Webhook

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

Features Description
Scoped configuration Webhooks are scoped at the team level. Mandatory set up process for each adds an Outgoing Webhook.
Reactive messaging Users must use @mention for the webhook to receive messages. Currently, 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 cannot 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 cannot 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

  1. Select Teams from the left pane. The Teams page appears:

    Teams channel

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

    Create Outgoing Webhook

  3. Select the Apps tab on the channel page:

    Create an Outgoing Webhook

  4. Select Create an Outgoing Webhook:

    Create Outgoing Webhooks

  5. 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.
  6. Select Create. The Outgoing Webhook is added to the current team's channel:

    create Outgoing Webhook

A Hash-based Message Authentication Code (HMAC) dialogue box appears. It is a security token used to authenticate calls between Teams and the designated outside service.

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 line of business app that tracks all CRUD operations, such as create, read, update, and delete. These operations are made to the employee records by Teams channel HR users across an Office 365 tenancy.

Create a URL on your app's server to accept and process a POST request with a JSON payload

Your service receives messages in a standard Azure bot service messaging schema. The Bot Framework connector is a RESTful service that empowers to process the interchange of JSON formatted messages through HTTPS protocols as documented in the Azure Bot Service API. Alternatively, you can follow the Microsoft Bot Framework SDK to process and parse messages. For more information, see overview of Azure Bot Service.

Outgoing Webhooks are scoped to the team level and are visible to all the team members. Users need to @mention the name of the Outgoing Webhook to invoke it in the channel.

Note

  • You can send Adaptive Card, Hero card, and text messages as attachment with Outgoing Webhook.
  • Cards support formatting. For more information, see format cards with markdown.

Following codes are examples of an Adaptive Card response:

string content = await this.Request.Content.ReadAsStringAsync();
Activity incomingActivity = JsonConvert.DeserializeObject<Activity>(content);

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 Samples to create custom bots to be used in Microsoft Teams. View View

See also