O que é um webhook (sem jargão)

Você preenche um formulário no site. Alguém no time precisa saber na hora. Abrir o painel a cada cinco minutos não é solução. Um webhook resolve isso: a ferramenta avisa sozinha quando algo acontece.

Neste guia, você entende o que é um webhook, quando ele faz mais sentido do que uma API “normal”, e o que cuidar para não virar um aviso confuso (ou inseguro).

A ideia em uma frase

Um webhook é um aviso automático. Quando um evento ocorre (formulário enviado, pagamento confirmado, pedido cancelado), o sistema envia uma mensagem para um endereço que você configurou.

Pense no porteiro do prédio. Em vez de você ligar a cada hora perguntando se chegou encomenda, o porteiro te chama quando ela chega. Você não fica perguntando. Você é avisado.

O que a ferramenta envia de verdade

Na prática, o webhook é um pedido HTTP (quase sempre POST) para uma URL sua. No corpo desse pedido, vão dados do evento.

Exemplo concreto: alguém preenche o formulário “Fale conosco”.

O que a ferramenta envia (resumo):

• evento: form_submitted
• nome: Maria
• email: maria@empresa.com
• mensagem: “Quero uma proposta”
• data e hora do envio

O que a sua URL devolve:

• status 200 (ou 2xx): “Recebi, pode seguir.”
• status de erro (4xx ou 5xx): “Não deu. Tente de novo.”

Esse “ok” importa. Muitas plataformas tentam reenviar se não receberem uma resposta de sucesso. Se a sua URL ficar lenta ou cair, você pode receber o mesmo aviso mais de uma vez.

Webhook vs API “normal”

Os dois usam a internet. A diferença é quem inicia a conversa.

Na API “normal” (você pergunta):

1. Seu sistema pergunta: “Teve pedido novo?”
2. A ferramenta responde: “Sim” ou “Não”.
3. Você precisa perguntar de novo depois.

No webhook (a ferramenta avisa):

1. Acontece o evento.
2. A ferramenta envia o aviso para a sua URL.
3. Seu sistema reage na hora (Slack, WhatsApp, email, planilha, CRM).

Use API “normal” quando você precisa buscar dados sob demanda, listar histórico, ou puxar informações em horário fixo. Use webhook quando o timing importa: algo aconteceu agora e alguém (ou outro sistema) precisa saber agora.

Muitos fluxos misturam os dois. O webhook avisa “pedido pago”. Depois, sua API busca detalhes completos se precisar.

Exemplo real: formulário vira aviso no time

Cenário: página de contato. Quando alguém envia, o time comercial deve ser avisado no Slack (ou WhatsApp, ou email).

Fluxo simples:

1. A pessoa envia o formulário.
2. A ferramenta (formulário, CRM ou automação) dispara o webhook.
3. Sua URL recebe os dados.
4. Seu sistema formata a mensagem e envia para o canal do time.

O “pedido feito” pode ser:

• método: POST
• destino: https://seusistema.com/webhooks/formulario
• corpo: nome, email, mensagem, origem da página

O “que a ferramenta devolve” (do ponto de vista dela) é a resposta da sua URL. Se você responder 200, o fluxo segue. Se responder erro, ela pode tentar outra vez.

Alternativas comuns no mesmo padrão:

• pagamento aprovado -> email de confirmação interno
• lead qualificado -> mensagem no WhatsApp do vendedor
• ticket aberto -> alerta no Slack do suporte

A lógica é a mesma: evento -> aviso -> ação.

Quando vale a pena usar

Webhooks brilham quando:

• o atraso atrapalha (lead quente, falha crítica, pedido urgente)
• várias ferramentas precisam reagir ao mesmo evento
• você quer menos “perguntar de novo a cada X minutos”

Eles são menos ideais quando:

• você só precisa de um relatório diário
• o sistema destino não tem URL pública estável
• o volume de eventos é alto e você ainda não tem fila ou controle de carga

Limites e cuidados (segurança e retries)

Webhooks são práticos, mas não são mágicos. Trate-os como entrada pública de dados.

Segurança básica:

• Use HTTPS.
• Valide se o aviso veio da ferramenta certa (token secreto na URL, assinatura no cabeçalho, ou ambos, conforme a plataforma oferecer).
• Não confie cegamente no conteúdo. Confira campos obrigatórios e formatos.
• Evite expor dados sensíveis no próprio corpo se não for necessário.

Retries (reenvios):

• Se sua URL falhar, a origem pode tentar de novo.
• Processe eventos de forma idempotente: o mesmo event_id não deve criar duas vendas, dois tickets ou duas mensagens iguais.
• Responda rápido (aceite o aviso) e processe o trabalho pesado depois, se possível.

Outros cuidados práticos:

• Logue o que chegou e o que falhou. Sem log, debugar webhook é adivinhar no escuro.
• Tenha um ambiente de teste. Muitas ferramentas permitem “enviar evento de exemplo”.
• Defina o que fazer se o Slack ou o WhatsApp estiver fora: guardar na fila, tentar de novo, ou avisar por outro canal.

Conclusão e próximo passo

Webhook é o porteiro digital: avisa quando algo acontece, sem você ficar perguntando. Para fluxos como “formulário preenchido -> aviso no time”, costuma ser mais simples e mais rápido do que ficar consultando a API a cada minuto.

Próximo passo: pegue uma ferramenta que você já usa (formulário, Stripe, HubSpot, Typeform, n8n, Make) e abra a tela de webhooks. Envie um evento de teste para uma URL sua, leia o corpo do pedido e responda 200. Esse exercício de dez minutos costuma esclarecer mais do que qualquer definição longa.