Como usar webhooks para receber eventos no teu workflow

Imagina que uma ferramenta de reuniões avisa quando um resumo fica disponível. O teu workflow pode receber o identificador, consultar o resumo e preparar tarefas para revisão. A chegada do aviso é apenas o início: ainda precisas de confirmar a reunião certa, os dados recebidos e o resultado produzido no destino.

Neste guia usamos um evento fictício de reunião para explicar o processo. Não é o contrato de uma plataforma específica nem uma integração executada de ponta a ponta. Os nomes dos campos são ilustrativos e devem ser substituídos pelos que a documentação do teu serviço realmente envia.

Quando faz sentido receber um webhook?

Usa um webhook quando a aplicação de origem consegue avisar sobre o acontecimento que interessa ao teu processo. Confirma que esse evento existe e inclui informação suficiente para iniciar o trabalho. Se a origem não o disponibilizar, pode ser necessário consultar periodicamente uma API ou escolher outro mecanismo suportado.

O evento deve corresponder ao estado de que precisas. «Reunião terminou» pode acontecer antes de o resumo estar pronto. Se o workflow depende do resumo, procura um evento de disponibilidade ou define como confirmar esse estado. Começar cedo demais pode produzir uma falha que parece aleatória, embora resulte de uma condição ainda não cumprida.

A documentação do nó Webhook do n8n descreve-o como uma entrada que pode iniciar um workflow a partir de dados recebidos. O nó HTTP Request faz o percurso complementar: pede informação a um endereço. Podes combinar os dois quando o evento só traz um identificador.

Antes de abrir o editor, desenha entrada, validação, consulta, ação e verificação. O guia sobre como desenhar uma automação antes de abrir o n8n ajuda a definir esse percurso. Acrescentar nós sem decidir o resultado esperado torna o diagnóstico mais difícil.

Que dados precisas de conhecer sobre o evento?

Confirma o tipo de evento, a estrutura enviada, os identificadores e as condições de entrega. Distingue o identificador do acontecimento do identificador do objeto a consultar. Regista também autenticação, prazos de resposta e comportamento perante falhas, porque estas regras determinam como o teu workflow deve aceitar e acompanhar cada entrada.

No exemplo, podes usar um corpo fictício como `{"event_id":"E-01","type":"meeting.summary_ready","meeting_id":"R-01"}`. O primeiro identificador serve para acompanhar o evento; o segundo identifica a reunião. Nenhum deles deve ser confundido com o número de uma linha numa folha ou com o nome dado ao workflow.

Lê a documentação do fornecedor e observa uma entrega de teste autorizada. Verifica se os dados chegam no corpo, nos cabeçalhos ou em parâmetros. Não uses automaticamente um campo chamado `id` sem perceber a que objeto pertence. Uma ligação tecnicamente válida pode consultar a reunião errada se esse significado estiver trocado.

Guarda uma amostra sintética com a estrutura necessária, sem dados pessoais nem segredos. Essa amostra permite repetir testes e pedir ajuda. Mantém claro que ela comprova o formato do ensaio, não a entrega real do serviço externo.

Como preparas a entrada de teste no n8n?

Cria um workflow de teste e acrescenta o nó Webhook com o método esperado pela origem. Escolhe um caminho identificável, configura a proteção adequada e usa o endereço de teste enquanto observas a entrada. Mantém as ações seguintes limitadas a dados fictícios e a um destino onde possas conferir o resultado.

Para o nosso ensaio com JSON, a proposta é receber um pedido POST. Copia o endereço mostrado pelo nó, sem o reconstruir à mão. Um pedido GET feito pelo navegador não substitui um POST com corpo e cabeçalhos. O método e o formato devem coincidir com o contrato que estás a testar.

Na documentação de desenvolvimento de webhooks, o n8n distingue o endereço de teste do endereço de produção. A opção «Listen for test event» prepara a receção temporária e permite observar os dados no editor. Se a escuta terminar, inicia-a novamente antes de repetir o envio.

Podes enviar o exemplo a partir de outro workflow com HTTP Request, conforme a orientação oficial de testes. Usa apenas o teu endereço de teste, o método combinado e a credencial de teste. Confere a entrada antes de acrescentar consultas ou escritas noutros serviços.

Como confirmas que o pedido vem da origem esperada?

Aplica o mecanismo de autenticação ou assinatura suportado pela aplicação que envia o evento. A validação deve acontecer antes de executar ações com os dados recebidos. Um endereço difícil de adivinhar, um nome de evento plausível ou um campo que diz «autorizado» não confirmam, por si só, quem enviou o pedido.

O n8n disponibiliza opções como Basic, Header e JWT nas suas credenciais de Webhook. A escolha tem de ser compatível com o emissor. Se o serviço não consegue enviar o cabeçalho que configuraste, a ligação precisa de outra solução documentada; retirar a proteção não resolve o contrato.

Alguns fornecedores assinam o conteúdo. O GitHub, por exemplo, documenta a validação da assinatura das entregas. Esse processo usa o conteúdo recebido e um segredo partilhado. Não equivale a verificar apenas se um cabeçalho existe ou se contém um valor fixo escolhido por ti.

Segue a implementação indicada pelo fornecedor e preserva os bytes necessários à verificação. Guarda segredos no mecanismo de credenciais apropriado, nunca no corpo de um exemplo público. Um filtro por tipo de evento também não substitui autenticação. Depois de reconhecer a origem, continua a validar o conteúdo e o âmbito da ação.

Que validações de conteúdo deves fazer antes de continuar?

Confirma que o evento pertence ao tipo esperado, inclui os campos obrigatórios e se refere a um objeto permitido no teu processo. Rejeita ou encaminha entradas incompletas de forma explícita. Mantém separados os dados recebidos e as decisões internas, para que o emissor não escolha livremente o destino ou os acessos do workflow.

No exemplo, o workflow só deve procurar um resumo se existir um identificador de reunião válido para a conta configurada. Um campo vazio não pode ser substituído por um identificador antigo que ficou no teste. Essa substituição silenciosa pode fazer o fluxo parecer funcional enquanto trata sempre a mesma reunião.

Nas aulas do Laboratório sobre tarefas após reuniões, este ponto aparece na passagem do identificador fixo para o valor recebido no evento. O método inclui conferir a correspondência entre reunião, resumo e conta. O guia sobre como ligar uma API ao n8n com HTTP Request desenvolve a consulta seguinte.

Limita também os campos que transportas. Se só precisas do identificador, do tipo e do estado, não copies o corpo inteiro para todos os nós. Um URL de destino enviado no evento não deve ser usado para encaminhar credenciais ou dados sem validação do endereço e da finalidade.

Quando deves responder à aplicação que enviou o evento?

Define o significado da resposta antes de escolher quando a enviar. Ela pode confirmar receção, aceitação para processamento ou conclusão de uma operação curta, conforme o contrato. Se o trabalho continuar depois, acompanha esse estado separadamente e garante que existe um registo fiável para recuperar falhas sem perder eventos aceites.

O n8n permite controlar a resposta com o nó Respond to Webhook. A posição desse nó e os caminhos que o atingem fazem parte do desenho. Confere a resposta tanto no percurso válido como nos casos rejeitados; não basta configurar um corpo JSON para o caso ideal.

Uma resposta imediata não comprova que o resumo foi consultado ou que a tarefa foi criada. Para trabalho demorado, pode fazer sentido validar, guardar o evento numa fila ou registo durável e confirmar a aceitação. Mas esse armazenamento e a recuperação têm de existir; não surgem automaticamente por responderes cedo.

Os prazos variam entre serviços. Confirma o limite da origem e o comportamento da infraestrutura usada. Evita deixar o emissor à espera de uma operação longa de IA. Se o pedido expirar, verifica primeiro se houve efeitos no destino antes de repetir o fluxo inteiro.

Como evitas criar tarefas duplicadas quando o evento se repete?

Define uma identidade estável para o evento e para a ação produzida, e guarda o estado do processamento. Quando chega uma repetição, consulta esse registo antes de criar novos efeitos. A regra deve resistir a entregas simultâneas e distinguir trabalho concluído de uma tentativa interrompida que ainda precisa de recuperação.

No nosso exemplo, receber `E-01` duas vezes não deve criar duas tarefas iguais para `R-01`. Podes usar uma chave que combine origem, conta e identificador do evento, conforme o contrato real. A identidade da tarefa pode precisar de informação adicional se uma reunião produzir várias ações distintas.

Uma consulta seguida de criação, feita sem proteção contra concorrência, pode falhar quando dois pedidos chegam ao mesmo tempo. Ambos podem ver «ainda não existe» e criar o registo. Para produção, usa um mecanismo que reserve a identidade de forma atómica ou uma operação de criação com chave única, conforme o armazenamento escolhido.

Mantém estados como recebido, em processamento, concluído e falhado. Se a criação no destino ocorreu mas a confirmação local falhou, a recuperação deve reconciliar o resultado antes de criar outra tarefa. É este cuidado que torna o processo repetível sem duplicar efeitos, frequentemente descrito como idempotência.

Distingue ainda repetição de atualização. Dois eventos diferentes podem referir-se à mesma reunião, por exemplo quando o resumo é corrigido. Ignorar tudo o que tenha o mesmo identificador de reunião pode impedir uma atualização necessária. Define se a nova versão deve atualizar as tarefas propostas, abrir uma revisão ou apenas ficar registada. Não alteres compromissos já aceites pela equipa só porque chegou outro texto.

Considera também a ordem de chegada. Um evento recebido mais tarde pode descrever um estado anterior. Usa a versão, a sequência ou outra indicação prevista no contrato, quando existir, e consulta o estado atual na origem se for necessário. Não inventes uma regra baseada apenas no relógio do teu workflow. O teste deve confirmar que uma entrega atrasada não substitui silenciosamente informação mais recente.

Que testes deves fazer além do primeiro pedido correto?

Testa entradas válidas, incompletas, não autorizadas e repetidas, além da indisponibilidade do destino. Para cada caso, define a resposta esperada, o estado guardado e os efeitos permitidos. O teste termina quando conferes esses resultados, incluindo a ausência de ações indevidas, e não apenas quando um nó aparece executado.

Usa uma lista curta de cenários e repete-os com dados fictícios. A tabela seguinte é uma proposta de verificação para o exemplo da reunião. Adapta os códigos de resposta e as decisões ao contrato do teu serviço, sem assumir que todos os fornecedores interpretam falhas da mesma forma.

Confere também dados fixados no editor. São úteis durante a construção, mas podem esconder a entrada real. Retira-os do percurso que estás a validar e volta a enviar um evento controlado. Uma execução com uma saída guardada não prova que o fornecedor entregou os dados naquele teste.

Como passas do teste para produção e acompanhas falhas?

Publica a versão revista do workflow, configura na origem o endereço de produção e confirma uma entrega autorizada de ponta a ponta. Acompanha evento, execução e resultado com identificadores relacionados. Mantém um procedimento para investigar falhas e repetir apenas o trabalho necessário, preservando credenciais e dados pessoais nos registos de apoio.

A publicação e o endereço correto são passos separados. A documentação do n8n indica que os dados de produção devem ser consultados nas execuções, em vez de esperares que apareçam na entrada do editor. Confere a retenção configurada, porque não deves depender de um histórico que pode já ter sido eliminado.

Não assumas reenvio automático universal. O GitHub, por exemplo, explica que não reenvia automaticamente entregas falhadas. Outros fornecedores têm regras diferentes. Regista a política da tua origem e define como detetar o que ficou por processar.

Quando surge um erro, localiza a etapa e compara entrada, configuração e destino. O artigo sobre transformar reuniões em tarefas com IA ajuda a rever a parte editorial das ações. Um webhook bem recebido não torna correta uma tarefa inventada nem confirma que o respetivo responsável a aceitou.

Como podes aprender isto no Laboratório da IA?

No Laboratório da IA podes aprender a desenhar e testar workflows, ligar serviços e conferir os dados que passam entre etapas. Tens aulas semanais, gravações e materiais para praticar. Nos Zooms de acompanhamento semanais podes trazer um exemplo, o erro observado e a etapa em que precisas de ajuda.

Começa com um evento fictício e um destino de teste. Quando conseguires explicar a origem, a validação, a resposta e a recuperação de uma falha, tens uma base mais clara para adaptar o fluxo ao teu negócio. A passagem para dados reais deve respeitar o processo e os acessos confirmados.