Build Outgoing Webhooks

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:

Screenshot shows Outgoing Webhooks in Teams channel.

Prerequisites

10 minutes remaining

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

9 minutes remaining

Open Microsoft-Teams-Samples.
Select Code.
From the dropdown menu, select Open with GitHub Desktop.
Select Clone.

Create Outgoing Webhooks

8 minutes remaining

Create a tunnel

dev tunnel
ngrok

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:
1. Account: Enter a Microsoft or GitHub account.
2. Name: Enter a name for your tunnel.
3. Tunnel Type: From the dropdown list, select Temporary.
4. 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.

Use ngrok or Command Prompt to create a tunnel to your locally running web server's publicly available HTTPS endpoints. Run the following command in ngrok:

ngrok http --host-header=localhost 3978

Tip

If you encounter ERR_NGROK_4018, follow the steps provided in the Command Prompt to sign up and authenticate ngrok. Then run the ngrok http --host-header=localhost 3978 command.

The window shows the HTTPS URL.

Screenshot shows the ngrok HTTPS 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/Sample or api/authenticatedSample, do the following:
  - For api sample, copy and paste the dev tunnel or ngrok URL and append it with /api/sample.
  - For api authenticatedSample, copy and paste the dev tunnel or ngrok URL 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

3 minutes remaining

Open Visual Studio.
Go to File > Open > Project/Solution....
From csharp folder, select WebhookSampleBot.sln file.
Go to AuthProvider.cs file. Update contoso to M365x70471008 and 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

2 minutes remaining

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

1 minutes remaining

Did you come up with something like this?

Screenshot shows the meeting chat that displays new message on desktop and mobile.

Congratulations!

100% complete!

You've completed the tutorial to get started with an Outgoing Webhook app!

Share via