Create Incoming Webhooks

Article
04/13/2023

An Incoming Webhook lets external applications share content in Microsoft Teams channels. The webhooks are used as tools to track and notify. The webhooks provide a unique URL, to send a JSON payload with a message in card format. Cards are user interface containers that include content and actions related to a single article. You can use cards in the following capabilities:

Bots
Message extensions
Connectors

Important

You can choose to build notification bot Teams app other than Incoming Webhooks. They perform similarly but notification bot has more functionalities. For more information, see Build notification bot with JavaScript or Incoming Webhook notification sample. To get started, download and explore Teams Toolkit. For more information, see Teams Toolkit documents.

Note

The message size limit is 28 KB. When the size exceeds 28 KB, you receive an error. For more information, see Limits and specifications for Microsoft Teams.
If more than four requests are made in a second, the client connection is throttled until the window refreshes for the duration of the fixed rate. A retry logic with exponential backoff can mitigate rate limiting for cases where requests exceed the limits within a second. To avoid hitting the rate limits, see HTTP 429 responses.

See the following video to learn how to create Incoming Webhooks:

Key features of Incoming Webhooks

The following table provides the features and description of an Incoming Webhook:

Features	Description
Adaptive Cards using an Incoming Webhook	Adaptive Cards can be sent through Incoming Webhooks. For more information, see Send Adaptive Cards using Incoming Webhooks.
Actionable messaging support	Actionable message cards are supported in all Microsoft 365 groups including Teams. If you send messages through cards, you must use the actionable message card format. For more information, see Legacy actionable message card reference and message card playground.
Independent HTTPS messaging support	Cards provide information clearly and consistently. Any tool or framework that can send HTTPS POST requests can send messages to Teams through an Incoming Webhook.
Markdown support	All text fields in actionable messaging cards support basic Markdown. Don't use HTML markup in your cards. HTML is ignored and treated as plain text.
Scoped configuration	Incoming Webhook is scoped and configured at the channel level.
Secure resource definitions	Messages are formatted as JSON payloads. This declarative messaging structure prevents the insertion of malicious code.

Note

Teams bots, message extensions, Incoming Webhook, and the Bot Framework support Adaptive Cards. Adaptive Card is an open cross-card platform framework that is used in all platforms such as Windows, Android, iOS, and so on. Currently, Teams connectors don't support Adaptive Cards. However, it is possible to create a flow that posts Adaptive Cards to a Teams channel.
For more information on cards and webhooks, see Adaptive cards and Incoming Webhooks.

Create Incoming Webhooks

To add an Incoming Webhook to a Teams channel, follow these steps:

Open the channel in which you want to add the webhook and select ••• from the upper-right corner.
Select Connectors from the dropdown menu.
Search for Incoming Webhook and select Configure.
Provide a name and upload an image for your webhook if necessary.
Select Create.
Copy and save the unique webhook URL present in the dialog. The URL maps to the channel and you can use it to send information to Teams.
Select Done.

The webhook is now available in the Teams channel.

You can create and send actionable messages through Incoming Webhook or connector for Microsoft 365 Groups. For more information, see Create and send messages.

Note

In Teams, select Settings > Member permissions > Allow members to create, update, and remove connectors, so that any team member can add, modify, or delete a connector.

Example

C#
JavaScript

Sample code reference

var adaptiveCardJson = @"{
  ""type"": ""message"",
  ""attachments"": [
    {
      ""contentType"": ""application/vnd.microsoft.card.adaptive"",
      ""content"": {
        ""type"": ""AdaptiveCard"",
        ""body"": [
          {
            ""type"": ""TextBlock"",
            ""text"": ""Message Text""
          }
        ],
        ""$schema"": ""http://adaptivecards.io/schemas/adaptive-card.json"",
        ""version"": ""1.0""
      }
    }
  ]
}";

var webhookUrl = "https://xxxxx.webhook.office.com/xxxxxxxxx";

var client = new HttpClient();
client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));

var content = new StringContent(adaptiveCardJson, System.Text.Encoding.UTF8, "application/json");
var response = await client.PostAsync(webhookUrl, content);

Sample code reference

 axios.post({{WebhookUrl}}, {{formatted_Card_Payload}})
    .then(res => {
        console.log(`statusCode: ${res.status}`)
        console.log(res)
    })
    .catch(error => {
        console.error(error)
    })