O que é webhook e como usar para um sistema avisar o outro

A Consultoria Trilha (fictícia) recebe pedidos de proposta por um formulário no site. Durante meses, alguém abria a caixa de entrada de hora em hora para ver se tinha chegado algum. Com um webhook, o formulário avisa o sistema da equipe no instante em que a pessoa aperta enviar, e a tarefa de resposta já nasce com o nome, o e-mail e a mensagem. Ninguém precisa conferir nada.

O texto abaixo explica como o webhook funciona, a diferença entre o de entrada e o de saída, o que o separa de API e de integração pronta, como protegê-lo e como testar antes de ligar. No fim, há um checklist para copiar e a forma de fazer isso no Mentrun.

Como funciona um webhook na prática?

Quem recebe cria um endereço na internet (a URL do webhook) que fica esperando avisos. Quando algo acontece no sistema A, ele faz uma chamada HTTP, quase sempre POST, para esse endereço levando os dados do ocorrido. O sistema B recebe, lê e age. Quem toma a iniciativa é quem tem a novidade, e não quem quer saber dela.

• O evento. O que dispara o aviso: formulário enviado, pagamento aprovado, tarefa concluída, reunião gravada.
• O endereço. Uma URL de quem recebe, em https, que o sistema A guarda e chama quando o evento acontece.
• O conteúdo. Quase sempre um texto em formato JSON, com os campos do ocorrido: nome, e-mail, valor, data, link.
• A resposta. Quem recebe devolve um “recebi” (um código HTTP 2xx, como 200 ou 202) para o sistema A saber que o aviso chegou. Sem isso, muitos remetentes tentam de novo.

Qual a diferença entre webhook de entrada e de saída?

Depende de qual lado você está. Webhook de entrada é quando o seu sistema recebe o aviso de outro. Webhook de saída é quando o seu sistema avisa outro. É o mesmo mecanismo visto dos dois lados, e uma empresa de serviço costuma ter os dois.

• Entrada: o formulário do site da Consultoria Trilha manda o contato para o sistema interno, que cria a tarefa de resposta.
• Saída: quando uma reunião com cliente é analisada, o sistema interno manda o resumo para a ferramenta onde o time de sucesso do cliente trabalha.

O que muda entre webhook, API e integração pronta?

A API é um cardápio de pedidos que você faz quando quiser. O webhook é o aviso que chega sem você pedir. A integração pronta é uma ponte já construída entre dois produtos, que você só liga. Os três se combinam, e a escolha depende do que cada sistema oferece.

Para um mapa de quando cada caminho vale, veja como integrar sistemas sem programar.

Como proteger um webhook?

Um webhook é uma porta aberta, então a regra é a de qualquer porta: só entra quem tem a chave. Use endereço https, uma chave que só os dois sistemas conhecem, assinatura do conteúdo quando o sistema oferecer e um jeito de ignorar aviso repetido.

• Chave ou segredo. O aviso só vale se vier com a chave combinada, num cabeçalho. Tratar o endereço com a chave embutida como senha: nada de colar em chat ou planilha.
• Assinatura. O remetente calcula um código do conteúdo com um segredo (o mais comum é HMAC-SHA256) e manda num cabeçalho. Quem recebe recalcula sobre o corpo exatamente como chegou, antes de converter o JSON, e compara. Se não bater, o aviso é descartado. Quando a assinatura inclui o horário, recuse aviso antigo.
• Aviso repetido. Redes falham e o remetente tenta de novo, então o mesmo aviso pode chegar mais de uma vez. Guarde o identificador do aviso (o id do evento ou um cabeçalho como Idempotency-Key) e ignore o que já foi processado, para não criar duas tarefas.
• Resposta rápida. Responda “recebi” logo e processe depois. Demora faz o remetente achar que falhou e mandar outra vez.

Como testar um webhook antes de ligar?

Teste com um aviso de exemplo antes de apontar o sistema de verdade para o endereço. Veja quais campos chegam, confira os nomes, rode o fluxo inteiro com dados fictícios e só então ligue. Teste que dispara mensagem a cliente real não é teste.

CHECKLIST: ANTES DE LIGAR UM WEBHOOK

Objetivo
[ ] Em uma frase: quando [evento] acontecer no sistema [A], o sistema [B] deve [ação].
[ ] Dono do webhook: [nome]. Quem recebe o alerta se falhar: [nome].

Conteúdo
[ ] Tenho um exemplo real do aviso (copiado do sistema A, sem dado de cliente).
[ ] Sei o nome de cada campo que vou usar e conferi maiúsculas e minúsculas.
[ ] Sei qual campo identifica o aviso (id do pedido, número do envio).

Segurança
[ ] O endereço é https.
[ ] Existe chave ou segredo, guardado em local controlado (não em planilha ou chat).
[ ] Sei como trocar a chave e quem avisa o outro lado.
[ ] Aviso repetido é ignorado.

Teste
[ ] Mandei um aviso de teste e os campos chegaram como esperado.
[ ] Testei com chave errada e o aviso foi recusado.
[ ] Testei o mesmo aviso duas vezes e nada foi duplicado.
[ ] O teste não mandou mensagem nem criou nada para cliente real.

Depois de ligar
[ ] No primeiro dia, olhei o histórico de execuções.
[ ] Combinei o que fazer se o outro sistema ficar fora do ar.

Como receber e enviar avisos no Mentrun?

No Mentrun, o webhook de entrada é o gatilho de uma automação, e o de saída é um passo pronto. Os dois ficam em Automações. O time técnico de quem vai integrar encontra exemplos de chave, aviso e assinatura na página Desenvolvedores, no rodapé do site.

1. 1

   Receber: escolha Ao receber de outro app (webhook)

   Em Automações › Fluxos, toque em Nova automação e, no Quando, escolha esse gatilho e toque em Gerar chave. Copie o endereço e a chave na hora e cole no outro app.

2. 2

   Escute um exemplo

   Toque em Escutar um exemplo e mande um aviso de teste do outro app (ou toque em Colar um exemplo). Os campos que chegaram aparecem na lista, com o valor.

3. 3

   Use os campos nos passos

   O botão { } mostra cada campo como Recebido: nome. Toque em Testar agora, que já usa o exemplo, e publique.

4. 4

   Enviar: use Enviar aviso para outro app

   No seletor de passos, em Outros apps, escolha Enviar aviso para outro app (webhook), cole o endereço que o outro sistema deu e, se ele pedir chave, escolha a chave guardada.

5. 5

   Teste a chamada

   Toque em Testar a chamada para mandar de verdade e ver a resposta. Deu certo? Publique.