Toda execução concluída de um agente produz um resultado, e o Vendelo entrega esse resultado por um de dois canais: e-mail, com um modelo padrão e o link de download, ou webhook, um POST para uma URL da sua escolha, com destinos prontos para Slack, Microsoft Teams, Discord e Google Chat ou um endpoint próprio. Este artigo mostra o que chega em cada canal, o envelope enviado ao webhook genérico, os cabeçalhos de segurança e a assinatura HMAC, o comportamento com cada aplicativo de chat e como validar a assinatura no seu servidor. Ao final, você saberá escolher o canal e configurar o destino com segurança.
Índice
Regra geral: link, não anexo
O arquivo gerado nunca viaja dentro do e-mail nem do corpo do webhook. Ele fica armazenado no Vendelo pelo prazo de retenção definido nas Configurações de IA (sete dias por padrão) e é compartilhado por um link de download. Isso mantém e-mails leves, evita bloqueios por tamanho e permite revogar o acesso ao expirar. Quem recebe o link consegue baixar sem login durante o prazo; trate o link como o próprio arquivo.
Escolha destinatários e canais que possam ver o conteúdo. O Vendelo não verifica as permissões de quem recebe; o filtro de dados é sempre o do proprietário do agente.
Entrega por e-mail
Com a entrega E-mail, cada destinatário do cadastro recebe uma mensagem com o modelo padrão do Vendelo, no idioma do agente, contendo:
- o assunto com o nome do agente;
- a frase “O agente X concluiu uma execução.”;
- os dados da execução: proprietário, gatilho (agendado ou manual), início, término e formato de saída;
- o arquivo gerado, com nome e tamanho, e o botão Baixar o arquivo;
- a data em que o link expira;
- nos formatos Texto simples e Markdown, uma prévia do resultado (até 1.500 caracteres).
O e-mail sai pela conta de envio configurada na instalação do Vendelo, a mesma usada pelas notificações. Se os e-mails do Vendelo caem em spam na sua empresa, os dos agentes cairão também; ajuste a lista de remetentes confiáveis.
Entrega por webhook
Com a entrega Webhook, ao concluir a execução o Vendelo faz um POST com corpo JSON para a URL cadastrada. O que vai no corpo depende do Destino do webhook escolhido no agente:
| Destino | Formato de saída JSON | Demais formatos |
|---|---|---|
| Genérico (endpoint próprio) | Envelope do Vendelo com o JSON do agente em data | Envelope do Vendelo com o link do arquivo |
| Slack | O JSON do agente é enviado como está, no contrato do webhook de entrada do Slack | Mensagem de texto no dialeto do Slack com o link de download |
| Microsoft Teams | Enviado como Adaptive Card. Se o JSON do agente não for um card, ele aparece formatado dentro de um card. | Adaptive Card com o texto e o link |
| Discord | Idem, no contrato do Discord | Mensagem de texto do Discord com o link, cortada em 2.000 caracteres (limite do Discord) |
| Google Chat | Idem, no contrato do Google Chat | Mensagem de texto do Google Chat com o link |
Com Texto simples ou Markdown, a mensagem dos aplicativos de chat traz a prévia do resultado e a frase “Esta execução não gerou arquivo.”. Com JSON, um conteúdo que não seja um objeto JSON é enviado como mensagem de texto.
O destino só responde com sucesso quando aceita o envio (status 2xx). Qualquer outro status, ou ausência de resposta em 30 segundos, é registrado como falha de entrega na execução.
Destino genérico: o envelope do Vendelo
O endpoint próprio recebe um JSON com estes campos:
| Campo | Conteúdo |
|---|---|
event | Tipo do evento. Hoje sempre ai_agent.run.succeeded. |
deliveryId | Identificador único da execução. Guarde e ignore repetições. |
companyId | Empresa da execução. |
agent | Identificador, nome e formato de saída do agente, e o proprietário (id, nome e sobrenome). |
run | Identificador, gatilho, início, término e tokens de entrada e saída. |
data | No formato JSON, o JSON produzido pelo agente (ou o texto, se o modelo não devolveu JSON válido). Nos demais formatos, o texto final do agente: completo em Texto simples e Markdown, um resumo nos formatos de arquivo. |
downloadUrl | Link de download do arquivo principal, válido pelo prazo de retenção. Nulo em Texto simples e Markdown. |
artifacts | Lista de arquivos com identificador, nome, tipo, tamanho, link e expiração. |
Slack, Microsoft Teams, Discord e Google Chat
Crie um webhook de entrada no aplicativo: no Slack, um “Incoming Webhook” no canal desejado; no Teams, um fluxo do Workflows (Power Automate) com o gatilho “Post to a channel when a webhook request is received”, porque o Teams aceita apenas Adaptive Card e o Vendelo envia nesse formato; no Discord, um webhook nas configurações do canal; no Google Chat, um webhook no espaço. Cada um fornece uma URL https.
Cole a URL no agente e escolha o destino correspondente.
Decida o formato: para mensagens formatadas pelo próprio agente, use formato JSON e peça, na descrição, que o agente produza exatamente o corpo aceito pelo aplicativo (a validação com a Filipa ajuda a escrever esse contrato). Para relatórios em arquivo, use o formato desejado; o canal receberá uma mensagem com o link.
Teste com Executar agora e confira a mensagem no canal.
Para o Teams com formato JSON, peça na descrição um Adaptive Card. Para o Slack, um JSON mínimo é um objeto com o campo
text. Peça ao agente: “responda exclusivamente com um JSON válido no formato aceito pelo webhook de entrada do Slack, com o campo text contendo o resumo, sem nenhum texto fora do JSON”.
Cabeçalhos e assinatura HMAC
Todo envio, para qualquer destino, leva cinco cabeçalhos HTTP que permitem confirmar a origem e evitar reenvios indevidos:
| Cabeçalho | Conteúdo |
|---|---|
X-Vendelo-Event | Tipo do evento (ai_agent.run.succeeded). |
X-Vendelo-Delivery | Identificador único da execução, para idempotência. |
X-Vendelo-Agent | Identificador do agente. |
X-Vendelo-Timestamp | Instante do envio em segundos Unix (UTC). Rejeite envios com mais de 5 minutos de diferença. |
X-Vendelo-Signature | sha256= seguido do HMAC-SHA256, em hexadecimal minúsculo, calculado com o segredo do webhook sobre a string “timestamp.corpo”. |
O segredo do webhook (prefixo whsec_) é gerado pelo Vendelo ao salvar o agente com a URL e aparece no cadastro com botão de copiar. Guarde-o apenas no servidor que recebe o webhook. Trocar só a URL mantém o mesmo segredo. Se ele vazar: apague a URL, mude a Entrega para E-mail, informe um destinatário e salve; depois volte para Webhook, cole a URL e salve. Um novo segredo é gerado.
Validando a assinatura no seu servidor
Leia o corpo bruto da requisição exatamente como recebido, antes de qualquer conversão.
Monte a string: valor de
X-Vendelo-Timestamp, um ponto, e o corpo bruto.Calcule HMAC-SHA256 dessa string usando o segredo como chave e converta para hexadecimal minúsculo.
Compare com o valor após
sha256=emX-Vendelo-Signature, em tempo constante. Se diferente, responda 401 e descarte.Responda 2xx só depois de aceitar o envio.
O Vendelo traz um exemplo pronto em Node.js na janela de ajuda do campo de webhook (ícone ao lado da URL), com botão para copiar. A lógica é a mesma em qualquer linguagem:
expected = "sha256=" + hex(HMAC_SHA256(secret, timestamp + "." + rawBody))
if (abs(now - timestamp) > 300s) reject 401
if (!constantTimeEquals(expected, X-Vendelo-Signature)) reject 401
if (alreadyProcessed(X-Vendelo-Delivery)) respond 200 and ignore
process(JSON.parse(rawBody)); respond 200Slack, Teams, Discord e Google Chat ignoram os cabeçalhos X-Vendelo, porque só conhecem o próprio formato. A assinatura é útil quando o destino é o seu servidor.
Falhas de entrega
Quando a geração termina bem mas a entrega não (e-mail recusado, webhook com erro ou sem resposta em 30 segundos), a execução fica com o status Concluído com falha na entrega no Histórico de execuções, e o arquivo continua disponível para download por lá durante o prazo de retenção. O mesmo status aparece quando o arquivo não foi devolvido pelo provedor ou passou do tamanho máximo; nesses casos não há arquivo para baixar. Falha de entrega não conta como falha de execução para a pausa automática. Corrija o destino (URL, segredo, canal) e use Executar agora para uma nova execução com entrega.
Perguntas frequentes
Posso entregar por e-mail e webhook ao mesmo tempo?
Não. Cada agente tem um tipo de entrega. Para os dois canais, cadastre dois agentes com a mesma instrução.
O e-mail chega com o arquivo anexado?
Não. Chega com o link de download, válido pelo prazo de retenção (sete dias por padrão). Só quando a instalação não tem endereço público de download o arquivo segue anexado.
O link de download exige login no Vendelo?
Não, enquanto o prazo de retenção não termina. Por isso, envie apenas a quem pode ver o conteúdo.
O Vendelo reenvia o webhook se o meu servidor estiver fora?
O envio é feito uma vez por execução. Se falhar, a execução registra a falha de entrega e o arquivo fica disponível no histórico. Use Executar agora para gerar e entregar de novo.
Meu servidor está atrás de um firewall. De onde vem o POST?
Do serviço de agentes da Vendelo, com o User-Agent Vendelo-Filipa-Agents/1.0. Peça ao administrador da Vendelo os endereços de saída da sua instalação para liberar no firewall.
Por que o Slack recebeu uma mensagem em vez do JSON?
Porque o formato de saída do agente não é JSON. Com formatos de arquivo, os aplicativos de chat recebem uma mensagem com o link.
O JSON do agente veio com texto fora do JSON e o Slack recusou.
Reforce na descrição que a resposta deve ser exclusivamente o JSON, sem comentários nem marcações de código, e valide de novo com a Filipa.
Próxima leitura
Histórico de execuções dos agentes: acompanhe cada execução, leia o resultado e baixe os arquivos gerados.
