创建传出 Webhook

传出 Webhook 充当机器人，并使用 @mention 在通道中搜索消息。 它向外部 Web 服务发送通知，并使用丰富的消息（包括卡片和图像）进行响应。 它有助于跳过通过 Microsoft Bot Framework 创建机器人的过程。

请参阅以下视频，了解如何创建传出 Webhook：

传出 Webhook 的主要功能

下表提供了传出 Webhook 的功能和说明：

功能	Description
作用域配置	Webhook 的作用域在团队级别。 每个的强制设置过程都会添加一个传出 Webhook。
重新激活消息传递	用户必须使用 webhook @mention 才能接收消息。 用户只能在公共频道中向传出 Webhook 发送消息，而不能在个人或专用范围内发送消息。
标准 HTTP 消息交换	响应与原始请求消息显示在同一链中，并且可以包含任何 Bot Framework 消息内容。 例如，格式文本、图像、卡片和表情符号。 尽管传出 Webhook 可以使用卡片，但它们不能使用除 openURL 以外的任何卡片操作。
Teams API 方法支持	传出 Webhook 会将 HTTP POST 发送到 Web 服务并获取响应。 它们无法访问任何其他 API，例如检索团队中的花名册或频道列表。

创建传出 Webhook

创建传出 Webhook 并向 Teams 添加机器人。 若要创建传出 Webhook，请按照以下步骤操作：

1. 从左窗格中选择“Teams”。

   

2. 在 “Teams ”页中，选择创建“传出 Webhook”所需的团队，然后选择“••”。

3. 从下拉菜单中选择“ 管理团队 ”。

   

4. 在频道页面上选择 “应用 ”。

   

5. 选择“ 创建传出 Webhook”。

   

6. 在 “创建传出 Webhook ”页中键入以下详细信息：

   • 名称：Webhook 标题和 @mention 选项卡。
   • 回叫 URL：接受 JSON 有效负载并接收来自 Teams 的 POST 请求的 HTTPS 终结点。
   • 说明：显示在个人资料卡和团队级应用仪表板中的详细字符串。
   • 个人资料图片：Webhook 的应用图标，可选。

7. 选择“创建”。 传出 Webhook 将添加到团队的频道。

   

此时将显示 基于哈希的消息身份验证代码 (HMAC) 对话框。 它是一个安全令牌，用于验证 Teams 与指定的外部服务之间的调用。 HMAC 安全令牌不会过期，并且对于每个配置都是唯一的。

注意

仅当 URL 有效并且服务器和客户端身份验证令牌相同时，团队的用户才可以使用传出 Webhook。 例如，HMAC 握手。

以下方案提供了添加传出 Webhook 的详细信息：

• 方案：将 Teams 频道数据库服务器上的更改状态通知推送到你的应用。
• 示例：你为组织 (LOB 应用) 构建了一个自定义应用，用于跟踪所有 CRUD (创建、读取、更新和删除) 操作。 这些操作由 Teams 频道 HR 用户跨 Microsoft 365 租户对员工记录进行。

URL JSON 有效负载

在应用服务器上创建 URL 以接受并处理具有 JSON 有效负载的 POST 请求

你的服务将在标准 Azure 机器人服务消息传递架构中接收消息。 Bot Framework 连接器是一项 RESTful 服务，它支持通过 Azure 机器人服务 API 中所述的 HTTPS 协议来处理 JSON 格式消息的交换。 或者，你也可以通过 Microsoft Bot Framework SDK 来处理和解析消息。 有关详细信息，请参阅 Azure 机器人服务概述。

传出 Webhook 的作用域为 team 级别，并且所有团队成员都可以看到。 用户需要 @mention 传出 Webhook 的名称才能在通道中调用它。

验证 HMAC 令牌

创建用于验证传出 Webhook HMAC 令牌的方法

使用入站消息和 ID 的示例：SigningKeyDictionary 的“contoso”，{"contoso", "vqF0En+Z0ucuRTM/01o2GuhMH3hKKk/N2bOmlM31zaA=" }。

在请求标头的授权中，使用值“HMAC 03TCao0i55H1eVKUusZOTZRjtvYTs+mO41mPL+R1e1U=”。

为确保你的服务仅接收来自实际 Teams 客户端的调用，Teams 在 HTTP hmac 授权标头中提供了 HMAC 代码。 始终在你的身份验证协议中包含此代码。

你的代码必须始终验证请求中包含的 HMAC 签名，如下所示：

• 从邮件的请求正文生成 HMAC 令牌。 大多数平台上都有一些标准库可以执行此操作，例如 Crypto for Node.js 和适用于 C# 的 Teams Webhook 示例 。 Microsoft Teams 使用标准 SHA256 HMAC 加密。 你必须将正文转换为采用 UTF8 格式的字节数组。
• 在客户端中注册传出 Webhook 时，将从 Teams 提供的安全令牌的字节数组计算哈希值。 请参阅创建传出 Webhook。
• 将哈希值转换为使用 UTF-8 编码的字符串。
• 将生成的哈希字符串值与 HTTP 请求中提供的值进行比较。

示例代码参考

public static AuthResponse Validate(AuthenticationHeaderValue authenticationHeaderValue, string messageContent, string claimedSenderId)
{
    //...
    string providedHmacValue = authenticationHeaderValue.Parameter;
    string calculatedHmacValue = null;
    try
    {
        byte[] serializedPayloadBytes = Encoding.UTF8.GetBytes(messageContent);
 
        byte[] keyBytes = Convert.FromBase64String(signingKey);
        using (HMACSHA256 hmacSHA256 = new HMACSHA256(keyBytes))
        {
            byte[] hashBytes = hmacSHA256.ComputeHash(serializedPayloadBytes);
            calculatedHmacValue = Convert.ToBase64String(hashBytes);
        }
 
        if (string.Equals(providedHmacValue, calculatedHmacValue))
        {
            return new AuthResponse(true, null);
        }
        else
        {
            string errorMessage = string.Format(
                "AuthHeaderValueMismatch. Expected:'{0}' Provided:'{1}'",
                calculatedHmacValue,
                providedHmacValue);
 
            return new AuthResponse(false, errorMessage);
        }
    }
    catch (Exception ex)
    {
        Trace.TraceError("Exception occcured while verifying HMAC on the incoming request. Exception: {0}", ex);
        return new AuthResponse(false, "Exception thrown while verifying MAC on incoming request.");
    }
}

回复方法

创建发送成功或失败回复的方法

来自传出 Webhook 的回复显示在与原始消息相同的回复链中。 当用户执行查询时，Teams 将向服务发出同步 HTTP 请求，并且你的代码在连接超时和终止之前有 5 秒时间回复消息。

示例响应

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

将自适应卡片与传出 Webhook 配合使用

你可以使用传出 Webhook 将自适应卡片、主图卡片和短信作为附件发送。 卡片支持格式设置。 有关详细信息，请参阅 使用 Markdown 格式化卡片。 传出 Webhook 中的自适应卡片仅 openURL 支持卡片操作。

以下代码是自适应卡片答复的示例：

C#/.NET

示例代码参考

// This method is to read the request body content
string content;
using (var reader = new StreamReader(Request.Body))
    {
        content = await reader.ReadToEndAsync();
    }

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;

JavaScript/Node.js

示例代码参考

var receivedMsg = JSON.parse(payload);
var responseMsg = JSON.stringify({
    "type": "message",
    "attachments": [
        {
            "contentType": "application/vnd.microsoft.card.adaptive",
            "contentUrl": null,
            "content": {
                "type": "AdaptiveCard",
                "version": "1.4",
                "body": [
                    {
                        "type": "TextBlock",
                        "text": "Request sent by: " + receivedMsg.from.name
                    },
                    {
                        "type": "Image",
                        "url": "https://c.s-microsoft.com/en-us/CMSImages/DesktopContent-04_UPDATED.png?version=43c80870-99dd-7fb1-48c0-59aced085ab6"
                    },
                    {
                        "type": "TextBlock",
                        "text": "Sample image for Adaptive Card."
                    }
                ]
            },
            "name": null,
            "thumbnailUrl": null
        }
    ]
});

JSON

{
 "type": "message",
 "attachments": [
  {
   "contentType": "application/vnd.microsoft.card.adaptive",
   "content": {
    "type": "AdaptiveCard",
    "version": "1.4",
    "body": [
     {
      "type": "TextBlock",
      "text": "Request sent by: Megan"
     },
     {
      "type": "Image",
      "url": "https://c.s-microsoft.com/en-us/CMSImages/DesktopContent-04_UPDATED.png?version=43c80870-99dd-7fb1-48c0-59aced085ab6"
     },
     {
      "type": "TextBlock",
      "text": "Sample image for Adaptive Card.."
     }
    ]
   }
  }
 ]
}

代码示例

示例名称	说明	.NET	Node.js
传出 webhook	此示例演示如何实现和使用传出 Webhook。	View	View

分步指南

按照分步指南，在 Teams 中创建传出 Webhook。

另请参阅

• Webhook 和连接器
• 创建和发送邮件
• 创建传入 Webhook
• 为 Microsoft 365 组创建连接器
• 自适应卡