Criar Webhooks de saída

O Webhook de Envio funciona como um bot e procura mensagens em canais com @mention. 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.

Veja o seguinte vídeo para saber como criar Webhooks de Envio:

Principais funcionalidades dos Webhooks de Envio

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 configuração obrigatório para cada um adiciona um Webhook de Envio.
Mensagens reativas	Os utilizadores têm de utilizar @mention para o webhook receber mensagens. Os utilizadores só podem enviar mensagens a um Webhook de Envio em canais públicos e não dentro do âmbito 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 Teams , selecione a equipa necessária para criar um Webhook de Envio e selecione •••.

3. Selecione Gerir equipa no menu pendente.

   

4. Selecione Aplicações na página do canal.

   

5. Selecione Criar um Webhook de Envio.

   

6. Escreva os seguintes detalhes na página Criar um webhook de envio :

   • Nome: o título do webhook e @mention separador.
   • 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 detalhada que aparece no cartão de perfil e no dashboard da aplicação ao nível da equipa.
   • Imagem de perfil: um ícone de aplicação para o seu webhook, que é opcional.

7. Selecione Criar. O Webhook de Envio é adicionado ao canal da equipa.

   

É apresentada uma caixa de diálogo HMAC (Message Authentication Code) baseada em Hash . É 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: tem uma aplicação personalizada criada para a sua organização (aplicação LOB) que controla todas as operações CRUD (criar, ler, atualizar e eliminar). Estas operações são efetuadas aos registos dos colaboradores por utilizadores de RH do canal do Teams num inquilino 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 utilizadores têm de @mention o nome do Webhook de Envio 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. Existem bibliotecas padrão para o fazer na maioria das plataformas, como o Crypto para Node.js e o exemplo de 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!"
}

Utilizar Cartões Ajustáveis com Webhooks de Envio

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, veja Formatar cartões com Markdown. O Cartão Ajustável em Webhooks de Envio suporta apenas openURL ações de cartões.

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 utilizar o 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 recebidos
• Criar conectores para Grupos do Microsoft 365
• Cartões Adaptáveis