Crear webhooks salientes

El webhook saliente actúa como bot y busca mensajes en canales mediante @mention. Envía notificaciones a un servicio web externo y responde con mensajes enriquecidos, que incluyen tarjetas e imágenes. Ayuda a omitir el proceso de creación de bots a través de Microsoft Bot Framework.

Vea el siguiente vídeo para obtener información sobre cómo crear webhooks salientes:

Características clave de los webhooks salientes

En la tabla siguiente se proporcionan las características y la descripción de los webhooks salientes:

Características	Descripción
Configuración con ámbito	Los webhooks tienen como ámbito el nivel de equipo. El proceso de instalación obligatorio para cada uno agrega un webhook saliente.
Mensajería reactiva	Los usuarios deben usar @mention para que el webhook reciba mensajes. Los usuarios solo pueden enviar mensajes a un webhook saliente en canales públicos y no dentro del ámbito personal o privado.
Intercambio de mensajes HTTP estándar	Las respuestas aparecen en la misma cadena que el mensaje de solicitud original y pueden incluir cualquier Bot Framework contenido del mensaje. Por ejemplo, texto enriquecido, imágenes, tarjetas y emojis. Aunque los webhooks salientes pueden usar tarjetas, no pueden usar ninguna acción de tarjeta excepto openURL.
Compatibilidad con el método de API de Teams	Los webhooks salientes envían una solicitud HTTP POST a un servicio web y obtienen una respuesta. No pueden acceder a ninguna otra API, como recuperar la lista de participantes o la lista de canales de un equipo.

Crear webhooks salientes

Crear webhooks salientes y agregar bots personalizados a Teams. Para crear un webhook saliente, siga estos pasos:

1. Seleccione Teams en el panel izquierdo.

   

2. En la página Teams , seleccione el equipo necesario para crear un webhook saliente y seleccione •••.

3. Seleccione Administrar equipo en el menú desplegable.

   

4. Seleccione Aplicaciones en la página del canal.

   

5. Seleccione Crear un webhook saliente.

   

6. Escriba los detalles siguientes en la página Crear un webhook saliente :

   • Nombre: el título del webhook y la pestaña @mention .
   • Dirección URL de devolución de llamada: el punto de conexión HTTPS que acepta cargas JSON y recibe solicitudes POST de Teams.
   • Descripción: cadena detallada que aparece en la tarjeta de perfil y en el panel de la aplicación de nivel de equipo.
   • Imagen de perfil: un icono de aplicación para el webhook, que es opcional.

7. Seleccione Crear. El webhook saliente se agrega al canal del equipo.

   

Aparece un diálogo de código de autenticación de mensajes basado en hash (HMAC ). Es un token de seguridad que se usa para autenticar las llamadas entre Teams y el servicio externo designado. El token de seguridad HMAC no expira y es único para cada configuración.

Nota:

El webhook saliente está disponible para los usuarios del equipo, solo si la dirección URL es válida y los tokens de autenticación de servidor y cliente son iguales. Por ejemplo, un protocolo de enlace HMAC.

En el escenario siguiente se proporcionan los detalles para agregar un webhook saliente:

• Escenario: enviar notificaciones de estado de cambios de inserción en un servidor de base de datos de canal de Teams a la aplicación.
• Ejemplo: tiene una aplicación personalizada creada para su organización (aplicación LOB) que realiza un seguimiento de todas las operaciones CRUD (creación, lectura, actualización y eliminación). Estas operaciones se realizan en los registros de empleados mediante el canal de Teams para los usuarios de RR. HH. en un inquilino de Microsoft 365.

Carga JSON de dirección URL

Crear una dirección URL en el servidor de la aplicación para aceptar y procesar una solicitud POST con una carga JSON

El servicio recibe mensajes en un esquema de mensajería estándar de Azure Bot Service. El conector de Bot Framework es un servicio RESTful que permite procesar el intercambio de mensajes con formato JSON a través de protocolos HTTPS, tal como se documenta en la API de Azure Bot Service. Como alternativa, puede seguir el SDK de Microsoft Bot Framework para procesar y analizar mensajes. Para obtener más información, consulte Información general de Azure Bot Service.

Los webhooks salientes se limitan al nivel de team y son visibles para todos los miembros del equipo. Los usuarios deben @mention el nombre del webhook saliente para invocarlo en el canal.

Comprobar token HMAC

Crear un método para comprobar el token HMAC de webhook saliente

Usando el ejemplo de mensaje entrante e identificador: "contoso" de SigningKeyDictionary de {"contoso", "vqF0En+Z0ucuRTM/01o2GuhMH3hK Bytes/N2bOmlM31zaA=" }.

Use el valor "HMAC 03TCao0i55H1eVKUusZOTZRjtvYTs+mO41mPL+R1e1U=" en la autorización del encabezado de solicitud.

Para asegurarse de que el servicio recibe llamadas solo de clientes reales de Teams, Teams proporciona un código HMAC en el encabezado de autorización HTTP hmac. Incluya siempre el código en el protocolo de autenticación.

El código siempre debe validar la firma HMAC incluida en la solicitud de la siguiente manera:

• Genere el token HMAC a partir del cuerpo de la solicitud del mensaje. Hay bibliotecas estándar para hacerlo en la mayoría de la plataforma, como Crypto para Node.js y ejemplo de webhook de Teams para C#. Microsoft Teams usa criptografía SHA256 HMAC estándar. Debe convertir el cuerpo en una matriz de bytes en UTF8.
• Calcule el hash de la matriz de bytes del token de seguridad proporcionado por Teams cuando registró el webhook saliente en el cliente de Teams. Consulte crear un webhook saliente.
• Convierta el hash en una cadena mediante codificación UTF-8.
• Compare el valor de cadena del hash generado con el valor proporcionado en la solicitud HTTP.

Referencia de código de ejemplo

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

Crear un método para enviar una respuesta correcta o errónea

Las respuestas de los webhooks salientes aparecen en la misma cadena de respuestas que el mensaje original. Cuando el usuario realiza una consulta, Teams emite una solicitud HTTP sincrónica al servicio y el código tiene cinco segundos para responder al mensaje antes de que se agote el tiempo de espera de la conexión y finalice.

Ejemplo de respuesta

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

Uso de tarjetas adaptables con webhooks salientes

Puede enviar mensajes de texto, tarjetas prominentes y tarjetas adaptables como datos adjuntos con un webhook saliente. Las tarjetas admiten el formato. Para obtener más información, consulte Formato de tarjetas con Markdown. La tarjeta adaptable de los webhooks salientes solo openURL admite acciones de tarjeta.

Los siguientes códigos son ejemplos de una respuesta de tarjeta adaptable:

C#/.NET

Referencia de código de ejemplo

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

Referencia de código de ejemplo

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

Ejemplo de código

Ejemplo de nombre	Descripción	.NET	Node.js
Webhooks salientes	En este ejemplo se muestra cómo implementar y usar el webhook saliente.	View	View

Guía paso a paso

Siga la guía paso a paso para crear webhooks salientes en Teams.

Vea también

• Webhooks y conectores
• Crear y enviar mensajes
• Creación de webhooks entrantes
• Creación de conectores para grupos de Microsoft 365
• Tarjetas adaptables