Migrar Webhooks de Microsoft Teams a Power Automate con Adaptive Cards

La inminente retirada de los Webhooks clásicos de Microsoft Teams obliga a las organizaciones a migrar con rapidez hacia mecanismos basados en Adaptive Cards y conectores modernos de Power Automate. Esta guía práctica explica en detalle cómo convertir integraciones que todavía envían MessageCards en flujos plenamente compatibles, sin perder funcionalidad ni reescribir toda la lógica.

Índice

Panorama de la retirada de Webhooks clásicos

Desde 2019 Microsoft viene advirtiendo que el esquema MessageCard (protocolo heredado de Office 365 Connectors) quedará obsoleto. Con el anuncio oficial —publicado en los mensajes de Microsoft 365 Roadmap— los Webhooks de canal dejarán de aceptar solicitudes que no cumplan el estándar Adaptive Card 1.x. Esto impacta a cualquier aplicación que hoy envíe tarjetas mediante el antiguo endpoint /webhookb2/, así como a los flujos de Power Automate cuyo disparador es When a HTTP request is received o los conectores “Post a message (V3)”. A partir de la fecha de corte:

Las tarjetas basadas en @type: "MessageCard" ya no se representarán en Teams.
Los pasos de Power Automate que esperan un nodo attachments provocarán errores de tipo nulo.
Microsoft fomentará explícitamente el uso de conectores certificados y el esquema application/vnd.microsoft.card.adaptive.

Diferencias clave entre MessageCard y Adaptive Card

Característica	MessageCard	Adaptive Card
Esquema	`@context` basado en schema.org	`$schema` propio de adaptivecards.io
Extensibilidad	Limitada a acciones básicas	Componentes ricos (`Action.Submit`, `Input.*`, etc.)
Interactividad	Solo vínculos externos	Entrada de datos, validación y actualización en línea
Renderizado	Depende del cliente Teams	Motor unificado para Teams, Outlook, Viva Connections
Soporte futuro	En retirada	Hoja de ruta activa (v1.6 y siguientes)

Escenario de partida: dos Webhooks con comportamientos divergentes

Webhook 1 continúa enviando un objeto JSON como el siguiente:

{
  "@context": "https://schema.org/extensions",
  "@type": "MessageCard",
  "themeColor": "0072C6",
  "title": "Alerta de compilación",
  "text":  "La build #77 falló en producción",
  "potentialAction": []
}

Al alcanzar el paso “Send adaptive card” del flujo V3, Power Automate arroja el error foreach expression … of type ‘Null’ porque attachments no existe.

Webhook 2 ya fue migrado: el remitente encapsula su tarjeta Adaptive dentro del campo payload. Esta integración funciona sin incidencias.

Opción 1: transformar el MessageCard dentro del flujo

Cuándo elegir esta opción

No tienes control sobre el sistema emisor o la ventana de mantenimiento es extremadamente corta.
Prefieres centralizar la lógica en Power Automate para evitar despliegues en múltiples microservicios.

Paso a paso detallado

Inserta un Compose inmediato tras el disparador Webhook.
Copia el siguiente fragmento en el editor de código del Compose:

{
  "type": "message",
  "attachments": [
    {
      "contentType": "application/vnd.microsoft.card.adaptive",
      "content": {
        "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
        "type": "AdaptiveCard",
        "version": "1.0",
        "body": [
          {
            "type": "TextBlock",
            "weight": "Bolder",
            "size": "Medium",
            "text": "@{triggerBody()?['title']}"
          },
          {
            "type": "TextBlock",
            "text": "@{triggerBody()?['text']}",
            "wrap": true
          }
        ]
      }
    }
  ]
}

Encadena la salida del Compose al conector “Post adaptive card and wait for a response” o “Send message (V3)”.
Guarda y prueba el flujo: la tarjeta renderizará correctamente y el error de tipo nulo desaparecerá.

Explicación técnica

El paso Compose convierte la carga flat del MessageCard en un objeto que cumple la interfaz de Teams: attachments[] con contentType = application/vnd.microsoft.card.adaptive. Al hacerlo:

Power Automate ya no intenta iterar sobre un valor nulo.
El flujo es agnóstico al nombre de los campos de origen; basta con usar expresiones @{triggerBody()?['campo']}.
Puedes añadir lógica condicional (If, Switch) para enriquecer la tarjeta (por ejemplo, cambiar el themeColor a un icono visual).

Ventajas y desventajas

	Ventajas	Desventajas
Transformación en Compose	No requiere cambios en el backend Reversible al instante	Aumenta la complejidad del flujo Puede impactar en el rendimiento si llegan miles de mensajes por hora

Opción 2: migrar la tarjeta en el sistema emisor

Por qué es la estrategia recomendada

Si tienes acceso al código que dispara el Webhook, lo más robusto es emitir directamente un Adaptive Card. Así:

La lógica de presentación vive donde corresponde: en la aplicación que conoce el dominio de negocio.
Reduces el tiempo de ejecución del flujo hasta un 25 %, porque eliminas pasos intermedios.
El mensaje llega a Teams con metadatos completos (actions, inputs, imágenes, etc.) sin necesidad de manipular objetos JSON en Power Automate.

Ejemplo de conversión en C#

// Antes: objeto MessageCard
var card = new {
  title = "Nueva incidencia",
  text  = "Se abrió el ticket #1452"
};

// Después: Adaptive Card 1.4
var adaptive = new {
\$schema = "[http://adaptivecards.io/schemas/adaptive-card.json](http://adaptivecards.io/schemas/adaptive-card.json)",
type = "AdaptiveCard",
version = "1.4",
body = new \[] {
new { type = "TextBlock", weight = "Bolder", text = card.title },
new { type = "TextBlock", wrap = true, text = card.text }
},
actions = new \[] {
new {
type  = "Action.OpenUrl",
title = "Ver incidencia",
url   = "[https://helpdesk.ejemplo.com/ticket/1452](https://helpdesk.ejemplo.com/ticket/1452)"
}
}
};
var json = JsonSerializer.Serialize(adaptive);
httpClient.PostAsync(webhookUrl, new StringContent(json, Encoding.UTF8, "application/json"));

Buenas prácticas

Mantén sincronizada la versión (1.0, 1.4, 1.6) con el Designer de Adaptive Cards para evitar propiedades no soportadas.
Implementa pruebas unitarias que validen el JSON contra el schema oficial.
Documenta un fallback (correo electrónico, log de auditoría) si la llamada al Webhook devuelve 4xx.

Opción 3: conectores de terceros ya actualizados

Algunos proveedores han publicado versiones renovadas de sus plugins tras el aviso de Microsoft. Atlassian, por ejemplo, liberó en agosto de 2024 un conector de Jira Cloud que envía Adaptive Cards nativas. El procedimiento típico es:

Instalar el nuevo conector desde la sección Apps de Teams.
Crear un flujo en la plantilla “Jira → Teams” que expone una URL Webhook compatible.
Registrar esa URL en los webhooks outgoing de Jira.
Asignar un plan Teams Premium si el paso requiere “Post adaptive card and wait for a response”.

El resultado es una migración casi automática, con soporte oficial y actualizaciones de seguridad gestionadas por el proveedor.

Cómo tomar la decisión adecuada

Una regla empírica: si posees el código fuente, migra en origen; si no, encapsula la transformación en Power Automate. El diagrama mental siguiente suele resolver el dilema:

¿Controlas el emisor? Sí → Opción 2.
No → continua.
¿El volumen supera 10 mensajes/minuto? Sí → Opción 2 (mejor rendimiento).
No → Opción 1 es aceptable.
¿Existe un conector certificado? Sí → Opción 3.
No → finaliza la evaluación.

Preguntas frecuentes

¿Qué ocurre si dejo el MessageCard sin migrar?

La tarjeta quedará sin renderizar; los usuarios verán un texto plano con un vínculo “Ver original”. Además, futuros clientes de Teams podrían bloquear la solicitud.

¿Necesito cambiar el dominio del Webhook?

No. La URL sigue siendo válida; lo que cambia es el payload JSON.

¿Puedo usar Adaptive Cards v2.0?

Sí, pero solamente los clientes de Teams con soporte para esa versión la renderizarán; se recomienda mantener v1.x hasta que Microsoft indique compatibilidad total.

Checklist de migración

Auditar todos los Webhooks de Teams y clasificar su esquema (grep “@type”: “MessageCard”).
Elegir la estrategia de transformación (Compose, backend, conector).
Actualizar o crear flujos de prueba en Power Automate con registro detallado (Run History).
Programar una ventana de cambio y notificar a los propietarios de canales.
Supervisar durante 72 h y revisar métricas de éxito (ratio 2xx vs 4xx).

Conclusión

La transición de MessageCard a Adaptive Card es inevitable, pero controlable. Si tu organización actúa antes de la retirada definitiva, evitarás interrupciones en los flujos de notificación, obtendrás tarjetas más ricas e interactivas y alinearás tu solución con la estrategia a largo plazo de Microsoft 365. Con las tres rutas descritas —Compose, migración en origen o conector de terceros— dispones de alternativas viables para cualquier escenario.

Migrar Webhooks de Microsoft Teams a Power Automate con Adaptive Cards