Build Outgoing Webhooks
Important
The existing Microsoft 365 (previously called Office 365) connectors across all cloud platforms are nearing deprecation, and the creation of new Microsoft 365 connectors will soon be blocked. For more information on the schedule and how the Workflows app provides a more flexible and secure experience, see retirement of Microsoft 365 connectors within Microsoft Teams.
Webhooks help Microsoft Teams to integrate with external apps. In Teams, the Outgoing Webhooks act as bot and search for messages in channels using @mention. The Outgoing Webhooks allow users to send messages to web services without performing the entire process of creating bots through Microsoft Bot Framework. The Outgoing Webhooks post data from Teams to any service capable of accepting JSON payload.
Key features of Outgoing Webhooks
- Send notifications to any external web service.
- Respond with rich text messages including cards and images.
- Receive messages in public channels and not within the personal or private scope.
- Send HTTP POST to web service and get response.
Note
The Outgoing Webhooks can't access any other APIs, such as retrieve the roster or list of channels in a team.
This step-by-step guide helps you to create Outgoing Webhooks in Teams. You'll see the following output:
Prerequisites
Ensure that you install the following tools and set up your development environment:
| Install | For using... | |
|---|---|---|
| Microsoft Teams | Microsoft Teams to collaborate with everyone you work with through apps for chat, meetings, and call all in one place. | |
| Visual Studio 2022 | You can install the enterprise version in Visual Studio 2022, and install the ASP.NET and web development workloads. Use the latest version. | |
| Dev tunnel | Teams app features (conversational bots, message extensions, and incoming webhooks) need inbound connections. A tunnel connects your development system to Teams. Dev tunnel is a powerful tool to securely open your localhost to the internet and control who has access. Dev tunnel is available in Visual Studio 2022 version 17.7.0 or later. or You can also use ngrok as a tunnel to connect your development system to Teams. It isn't required for apps that only include tabs. This package is installed within the project directory (using npm devDependencies). |
Note
After downloading ngrok, sign up and install authtoken.
Set up local environment
Open Microsoft-Teams-Samples.
Select Code.
From the dropdown menu, select Open with GitHub Desktop.
Select Clone.
Create Outgoing Webhooks
Create a tunnel
Open Visual Studio.
Select Create a new project.
In the search box, enter ASP.NET. From the search results, select ASP.NET Core Web App.
Select Next.
Enter Project name and select Next.
Select Create.
An overview window appears.
In the debug dropdown list, select Dev Tunnels (no active tunnel) > Create a Tunnel....
A pop-up window appears.
Update the following details in the pop-up window:
- Account: Enter a Microsoft or GitHub account.
- Name: Enter a name for your tunnel.
- Tunnel Type: From the dropdown list, select Temporary.
- Access: From the dropdown list, select Public.
Select OK.
A pop-up window appears showing that dev tunnel is successfully created.
Select OK.
You can find the tunnel you've created in the debug dropdown list as follows:
Select F5 to run the application in the debug mode.
If a Security Warning dialog appears, select Yes.
A pop-up window appears.
Select Continue.
The dev tunnel home page opens in a new browser window and the dev tunnel is now active.
Go to Visual Studio, select View > Output.
From the Output console dropdown menu, select Dev Tunnels.
The Output console shows the dev tunnel URL.
Go to Teams and select Teams from the left pane.
Go to a team that you want, select More options (•••), and then select Manage team.
Select the Apps tab from the navigation bar.
Select Create an outgoing webhook from the lower-right corner of the window.
Enter the following details:
Name: The webhook title in @mention tab.
Callback URL: The URL generated from ngrok that accepts JSON payloads and receives POST requests from Teams. To use the
api/Sampleorapi/authenticatedSample, do the following:For api sample, copy and paste the
dev tunnelorngrokURL and append it with/api/sample.For api authenticatedSample, copy and paste the
dev tunnelorngrokURL and append it with/authenticatedSample?id=contoso.
Description: A detailed string that appears in the profile card and the team-level app dashboard.
Profile picture (optional): App icon for your webhook.
Select Create. The Outgoing Webhook is added to the current team's channel.
A
Hash-based Message Authentication Code (HMAC)dialog appears. You can use the security token in AuthProvider.cs file to authenticate calls between Teams and any designated outside services.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.
Build and run the service
Open Visual Studio.
Go to File > Open > Project/Solution....
From csharp folder, select WebhookSampleBot.sln file.
Go to AuthProvider.cs file. Update
contosotoM365x70471008and add HMAC.
Press F5 to run the project.
Select Yes if the following dialog appears:
A webpage displays local host information.
Interact with the app in Teams
Go to Teams and select Teams from the left pane.
Go to General > New conversation.
To invoke an Outgoing Webhook in the channel, @mention the Outgoing Webhook name and select the Send icon.
Note
You can send Adaptive Card, Hero card, and text messages as attachment with Outgoing Webhook.
The meeting chat displays a new message.
Complete challenge
Did you come up with something like this?
Congratulations!
You've completed the tutorial to get started with an Outgoing Webhook app!
Have an issue with this section? If so, please give us some feedback so we can improve this section.
Platform Docs