Introdução
Com o fim dos Webhook Connectors clássicos do Microsoft Teams, muitas organizações descobriram que seus alertas e integrações críticas pararam de chegar aos canais. Felizmente, é possível migrar seus Webhooks existentes para os novos padrões do Teams sem reescrever sistemas inteiros. A seguir, mostramos como adaptar rapidamente um payload MessageCard para Adaptive Card e manter o seu fluxo no Power Automate funcionando.
Por que os Webhooks Clássicos Estão Sendo Descontinuados?
Desde 2024 a Microsoft vem sinalizando que o esquema MessageCard está obsoleto. A partir de 2025, apenas cartões no formato Adaptive Card v1.0+ são aceitos pelos canais do Teams. A mudança traz recursos de acessibilidade, personalização responsiva e maior segurança, mas deixa muitas integrações quebradas.
Efeito imediato nos fluxos Power Automate
Fluxos que utilizam o gatilho When an HTTP request is received e o conector Post adaptive card in a chat or channel podem falhar quando o corpo recebido não apresenta um array attachments com o tipo correto. A mensagem de erro mais comum é:
foreach expression … 'attachments' is of type 'Null'Estudo de Caso: Webhook 1 x Webhook 2
Em nossa organização, dois Webhooks coexistiam:
- Webhook 1 – Enviava payload MessageCard. Não era possível alterar o código fonte.
- Webhook 2 – Um script Python que foi facilmente ajustado para Adaptive Card (anexando o campo
contentType: application/vnd.microsoft.card.adaptive).
Objetivo: transformar o Webhook 1 dentro do próprio fluxo, sem mexer no sistema emissor.
Estratégias de Migração Comparadas
| Estratégia | Como aplicar | Observações |
|---|---|---|
| Transformar no Flow | Após o gatilho, adicione uma ação Compose (ou Parse JSON) que receba o corpo original. Monte manualmente o array attachments contendo um objeto com contentType: application/vnd.microsoft.card.adaptive e mova os campos relevantes do MessageCard. Encaminhe o resultado para Post adaptive card in a chat or channel. | Exemplo real no repositório GitHub (issue #3920) sobre Prometheus Alertmanager. |
| Atualizar a integração de origem | Caso o serviço emissor já ofereça um novo conector (ex.: Jira Cloud ≥ 24 ago 2024), crie um webhook direto para o Teams já com Adaptive Card. | Costuma exigir configurar credenciais do Teams e, em alguns serviços, licença Teams Premium. |
| Camada intermediária | Substitua o endpoint original por uma Função Azure ou Logic App que converta MessageCard → Adaptive Card e, em seguida, chame o fluxo Power Automate. | Útil quando o Flow não pode ser modificado e o sistema emissor está fora do seu controle. |
Passo a Passo: Convertendo dentro do Flow
1. Preparar o gatilho
Crie ou edite um fluxo existente com o gatilho When an HTTP request is received. Copie e cole o esquema JSON mínimo para aceitar qualquer MessageCard:
{
"type": "object",
"properties": {
"@type": { "type": "string" },
"themeColor": { "type": "string" },
"title": { "type": "string" },
"text": { "type": "string" },
"sections": { "type": "array" },
"potentialAction": { "type": "array" }
}
}2. Compor o Adaptive Card
Insira uma ação Compose com o conteúdo abaixo (adapte ao seu caso):
{
"type": "message",
"attachments": [
{
"contentType": "application/vnd.microsoft.card.adaptive",
"content": {
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
"version": "1.5",
"body": [
{
"type": "TextBlock",
"size": "Medium",
"weight": "Bolder",
"text": "@{triggerBody()?['title']}"
},
{
"type": "TextBlock",
"wrap": true,
"text": "@{triggerBody()?['text']}"
}
],
"actions": [
{
"type": "Action.OpenUrl",
"title": "Abrir Detalhes",
"url": "@{items('LoopActions')?['url']}"
}
]
}
}
]
}3. Publicar no Teams
Adicione a ação Post adaptive card in a chat or channel, aponte para o canal desejado e passe a saída da ação Compose como corpo da mensagem.
4. Aproveitando complexidade existente
Caso o seu MessageCard possua seções múltiplas ou botões (potentialAction), crie um Apply to each que percorra esses arrays e gere componentes TextBlock ou Action.OpenUrl equivalentes.
Por dentro da transformação de esquema
O elemento mais importante é garantir que o seu objeto final possua attachments[0].contentType exatamente igual a application/vnd.microsoft.card.adaptive. Se esse campo estiver ausente, o conector do Teams tentará tratar o corpo como texto simples.
Dica de desempenho
Prefira Compose a Parse JSON quando quiser apenas reorganizar dados. O Parse JSON faz validação adicional e pode cair em rate limits se você receber milhares de eventos.
Atualizando a integração de origem
Quando você controla o sistema que gera o Webhook, migrar logo na fonte costuma ser o caminho mais limpo. Por exemplo, ao usar Jira Automation:
- Crie um novo Outgoing Webhook e aponte para
https://outlook.office.com/webhook/…. - Troque a opção MessageCard por Adaptive Card (Jira oferece um modelo desde agosto de 2024).
- Simule o gatilho e revise no Designer de Adaptive Cards se o visual está alinhado às diretrizes de marca.
Quando usar uma Camada Intermediária
Se seu fluxo estiver congelado em produção, mas o emissor é um SaaS sem opção de upgrade, crie uma Função Azure serverless.
module.exports = async function (context, req) {
const msg = req.body;
const card = {
type: 'message',
attachments: [{
contentType: 'application/vnd.microsoft.card.adaptive',
content: {
$schema: 'http://adaptivecards.io/schemas/adaptive-card.json',
version: '1.5',
body: [
{ type: 'TextBlock', text: msg.title, weight: 'Bolder' },
{ type: 'TextBlock', text: msg.text, wrap: true }
]
}
}]
};
await fetch(process.env.POWERFLOWURL, {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify(card)
});
context.res = { status: 202 };
};Desse modo, nenhum serviço precisa saber que houve alteração de formato; a transformação é transparente.
Boas Práticas para Migração em Massa
- Biblioteca única – Centralize a lógica de conversão (JavaScript, Python ou Logic Apps) e reutilize em todos os fluxos.
- Documentação de mapeamento – Registre cada campo original → novo campo. Facilita futuras atualizações para versões do Adaptive Card.
- Logs detalhados – Inclua Run history no Power Automate e, quando usar Funções Azure, envie métricas para o Application Insights.
- Ambiente de teste – Publique cartões em um canal privado antes de subir para produção. Isso garante que quebras de layout ou caracteres especiais sejam detectados.
Checklist Rápido de Conversão
| # | Item | OK? |
|---|---|---|
| 1 | attachments[0].contentType presente | |
| 2 | Versão do esquema $schema → “1.5” | |
| 3 | Texto principal no campo body[0].text | |
| 4 | Botões convertidos em Action.OpenUrl | |
| 5 | Validação no Designer |
Perguntas Frequentes (FAQ)
O MessageCard será totalmente bloqueado?
Sim. Desde setembro de 2025 o Teams recusa qualquer novo cartão MessageCard. Flows existentes que geram mensagens simples sem cartões continuam.
Preciso do Teams Premium para postar Adaptive Cards?
Não. A criação de cartões é gratuita. Apenas algumas automações nativas (ex.: aprovações avançadas) exigem licenças adicionais.
Consigo mandar HTML puro?
O conector “Post message” aceita texto markdown e menções, mas não aceita HTML. Qualquer estrutura visual deve ser um Adaptive Card.
Conclusão
Migrar de MessageCard para Adaptive Card pode parecer complexo, mas na prática envolve:
- Identificar Webhooks que ainda usam o formato antigo;
- Escolher a estratégia (transformar no Flow, atualizar origem ou criar camada intermediária);
- Executar testes em ambiente controlado;
- Monitorar e documentar o processo para novas integrações.
Com essas etapas, você não só mantém a continuidade dos seus alertas como também se prepara para explorar recursos avançados de interatividade que o novo modelo oferece, como entrada de dados, temas dinâmicos e suporte aprimorado a dispositivos móveis.