Add custom bots to Microsoft Teams with outgoing webhooks

What are outgoing webhooks in Teams?

Webhooks are a great way for Teams to integrate with external apps. A webhook is essentially a POST request sent to a callback URL. In Teams, outgoing webhooks provide a simple way to allow users to send messages to your web service without having to go through the full process of creating bots via the Microsoft Bot Framework. Outgoing webhooks post data from Teams to any chosen service capable of accepting a JSON payload. Once an outgoing webhook is added to a team, it acts like bot, listening in channels for messages using @mention, sending notifications to external web services, and responding with rich messages that can include cards and images.

Outgoing webhook key features

Feature Description
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. Currently users can only message an outgoing webhook in public channels and not within the personal or private scope
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). Note: Although outgoing webhooks can use cards, they cannot use any card actions except for openURL.
Teams API method support In Teams, outgoing webhooks send an HTTP POST to a web service and process a response back. They cannot access any other APIs like retrieve the roster or list of channels in a team.

Adding outgoing webhook processing to your app

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 made to employee records by Teams channel HR users across an Office 365 tenancy.

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

Your service will receive messages in the standard Azure bot service messaging schema. The Bot Framework connector is a RESTful service that enables your service to process the interchange of JSON formatted messages via HTTPS protocols as documented in the Azure Bot Service API. Alternatively, you can follow the [Microsoft Bot Framework SDK] to process and parse messages. See also About Azure Bot Service.

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

2. Create a method to verify the outgoing webhook HMAC token

To ensure that your service is receiving calls only from actual Teams clients, Teams provides an HMAC Code in the HTTP hmac header that should always be included in your authentication protocol.

Your code should always validate the HMAC signature included in the request:

  • Generate the HMAC token from the request body of the message. There are standard libraries to do this on most platforms (see Crypto for Node.js or see Teams Webhook Sample for C#). Microsoft Teams uses standard SHA256 HMAC cryptography . You will need to 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, below.
  • 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.

3. Create a method to send a success or failure response

Responses from your outgoing webhook will appear in the same reply chain as the original message. When the user performs a query, Microsoft Teams issues a synchronous HTTP request to your service and your code will have 5 seconds to respond to the message before the connection times out and terminates.

Example response

    "type": "message",
    "text": "This is a reply!"

Create an outgoing webhook

  1. Select the appropriate team and select Manage team from the (•••) drop-down menu.
  2. Choose the Apps tab from the navigation bar.
  3. From the window's lower right corner select Create an outgoing webhook.
  4. In the resulting popup window complete the required fields:
  • Name - The webhook title and @mention tap.
  • Callback URL - The HTTPS endpoint that accepts JSON payloads and will receive POST requests from Teams.
  • Description - A detailed string that will appear in the profile card and the team-level App dashboard.
  • Profile Picture (optional) an app icon for your webhook.
  • Select the Create button from lower right corner of the pop-up window and the outgoing webhook will be added to the current team's channels.
  • The next dialog window will display an Hash-based Message Authentication Code (HMAC) security token that will be used to authenticate calls between Teams and the designated outside service.
  • If the URL is valid and the server and client authentication tokens are equal (i.e., an HMAC handshake), the outgoing webhook will be available to the team's users.

Code samples

You can view outgoing webhook code samples on GitHub: