Criar Webhooks de saída

O Webhook de Saída atua como um bot e pesquisa mensagens em canais usando @menção. Ele envia notificações para um serviço Web externo e responde com mensagens avançadas, que incluem cartões e imagens. Ele ajuda a ignorar o processo de criação de bots por meio do Microsoft Bot Framework.

Confira o vídeo a seguir para saber como criar webhooks de saída:

Principais recursos de Webhooks de Saída

A tabela a seguir fornece os recursos e a descrição do Webhook de Saída:

Recursos	Descrição
Configuração com escopo	Os webhooks são definidos no nível da equipe. O processo de instalação obrigatório para cada um adiciona um Webhook de saída.
Mensagens reativas	Os usuários devem usar @menção para que o webhook receba mensagens. Atualmente, os usuários só podem enviar mensagens a um Webhook de Saída em canais públicos e não dentro do escopo pessoal ou privado.
Troca de mensagens HTTP padrão	As respostas aparecem na mesma cadeia da mensagem de solicitação original e podem incluir qualquer conteúdo de mensagem do Bot Framework. Por exemplo, rich text, imagens, cartões e emojis. Embora os Webhooks de Saída possam utilizar cartões, eles não podem utilizar nenhuma ação de cartão, exceto para openURL.
Suporte ao método de API do Teams	Webhooks de saída enviam um HTTP POST para um serviço Web e obtém uma resposta. Eles não podem acessar nenhuma outra API, como recuperar a lista de participantes ou a lista de canais em uma equipe.

Criar Webhooks de saída

Criar Webhooks de Saída e adicionar bots personalizados ao Teams. Para criar um Webhook de Saída, siga estas etapas:

1. Selecione Teams no painel esquerdo.

   

2. Na página Do Teams , selecione a equipe necessária para criar um Webhook de saída e selecione •••.

3. Selecione Gerenciar equipe no menu suspenso.

   

4. Selecione Aplicativos na página do canal.

   

5. Selecione Criar um Webhook de Saída.

   

6. Digite os seguintes detalhes na página Criar um webhook de saída :

   • Nome: o título do webhook e a guia @menção.
   • URL de retorno de chamada: o ponto de extremidade HTTPS que aceita cargas JSON e recebe solicitações POST do Teams.
   • Descrição: uma cadeia de caracteres detalhada que aparece no perfil cartão e no aplicativo de nível de equipe dashboard.
   • Imagem de perfil: um ícone de aplicativo para o webhook, que é opcional.

7. Selecione Criar. O Webhook de saída é adicionado ao canal da equipe atual.

   

Um diálogo HMAC (Código de Autenticação de Mensagem baseado em Hash) é exibido. É um token de segurança usado para autenticar chamadas entre o Teams e o serviço externo designado. O token de segurança do HMAC não expira e é exclusivo para cada configuração.

Observação

O Webhook de Saída estará disponível para os usuários da equipe somente se a URL for válida e os tokens de autenticação do servidor e do cliente forem iguais. Por exemplo, um handshake HMAC.

O cenário a seguir fornece os detalhes para adicionar um Webhook de Saída:

• Cenário: enviar notificações de status de alteração por push em um servidor de banco de dados de canal do Teams para seu aplicativo.
• Exemplo: você tem um aplicativo personalizado criado para seu aplicativo LOB (organização) que rastreia todas as operações CRUD (criar, ler, atualizar e excluir). Essas operações são feitas para os registros de funcionários por usuários de RH do Canal do Teams em um locatário do Microsoft 365.

Carga JSON da URL

Crie uma URL no servidor do aplicativo para aceitar e processar uma solicitação POST com uma carga JSON

Seu serviço recebe mensagens em um esquema de mensagens padrão do serviço de bot do Azure. O conector do Bot Framework é um serviço RESTful que permite processar o intercâmbio de mensagens formatadas em JSON por meio de protocolos HTTPS, conforme documentado na API do Serviço de Bot do Azure. Como alternativa, você pode seguir o SDK do Microsoft Bot Framework para processar e analisar mensagens. Para obter mais informações, consulte Visão geral do Serviço de Bot do Azure.

Os Webhooks de saída têm como escopo o nível team e são visíveis para todos os membros da equipe. Os usuários precisam @menção o nome do Webhook de saída para invocá-lo no canal.

Verificar o token HMAC

Criar um método para verificar o token HMAC do Webhook de Saída

Usando o exemplo de mensagem de entrada e ID: "contoso" de SigningKeyDictionary de {"contoso", "vqF0En+Z0ucuRTM/01o2GuhMH3hKKey/N2bOmlM31zaA=" }.

Use o valor "HMAC 03TCao0i55H1eVKUusZOTZRjtvYTs+mO41mPL+R1e1U=" na autorização do cabeçalho da solicitação.

Para garantir que seu serviço esteja recebendo chamadas somente de clientes reais do Teams, o Teams fornece um código HMAC no cabeçalho de autorização HTTP hmac. Sempre inclua o código em seu protocolo de autenticação.

Seu código sempre deve validar a assinatura HMAC incluída na solicitação da seguinte maneira:

• Gere o token HMAC do corpo da solicitação da mensagem. Há bibliotecas padrão para fazer isso na maioria das plataformas, como o exemplo de criptografia para Node.js e webhook do Teams para C#. O Microsoft Teams usa criptografia HMAC SHA256 padrão. Você deve converter o corpo em uma matriz de bytes em UTF8.
• Compute o hash da matriz de bytes do token de segurança fornecido pelo Teams quando você registrou o Webhook de Saída no cliente do Teams. Consulte Criar um Webhook de Saída.
• Converta o hash em uma cadeia de caracteres usando a codificação UTF-8.
• Compare o valor da cadeia de caracteres do hash gerado com o valor fornecido na solicitação HTTP.

Referência de código de exemplo

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.");
    }
}

Método para responder

Criar um método para enviar uma resposta de êxito ou falha

As respostas de seus Webhooks de Saída aparecem na mesma cadeia de resposta que a mensagem original. Quando o usuário realiza uma consulta, o Teams emite uma solicitação HTTP síncrona para seu serviço e seu código recebe cinco segundos para responder à mensagem antes que a conexão expire e termine.

Resposta de exemplo

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

Usar cartões adaptáveis com webhooks de saída

Você pode enviar mensagens de texto, Cartão Hero e Cartão Adaptável como anexo com o Webhook de Saída. Os cartões dão suporte à formatação. Para obter mais informações, consulte formatar cartões com Markdown. O Cartão Adaptável em Webhooks de Saída dá suporte apenas openURL a ações cartão.

Os códigos a seguir são exemplos de uma resposta de Cartão Adaptável:

C#/.NET

Referência de código de exemplo

// 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

Referência de código de exemplo

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.."
     }
    ]
   }
  }
 ]
}

Exemplo de código

Nome de exemplo	Descrição	.NET	Node.js
Webhooks de Saída	Este exemplo mostra como implementar e usar webhook de saída.	View	View

Guias passo a passo

Siga o passo a passo para webhooks de saída no Teams.

Confira também

• Webhooks e conectores
• Criar e enviar mensagens
• Criar webhooks de entrada
• Criar conectores para Grupos do Microsoft 365
• Cartões Adaptáveis