Webhook
O Que É Webhook
Webhook é um mecanismo de comunicação entre sistemas onde um sistema envia dados automaticamente para outro quando um evento específico ocorre, sem que o destinatário precise ficar pedindo atualizações. É o oposto de uma chamada de API tradicional (polling): em vez de o seu sistema perguntar repetidamente “tem novidade?”, o sistema externo avisa você proativamente quando algo relevante acontece.
A analogia mais intuitiva é o correio versus o e-mail. Com uma API tradicional, você vai até os Correios todos os dias perguntar se tem carta (polling). Com webhook, os Correios chegam na sua porta quando tem algo para entregar (push). Para sistemas que precisam reagir a eventos em tempo real, a diferença é enorme em eficiência e velocidade de resposta.
O mecanismo técnico é simples: você fornece uma URL (endpoint) do seu sistema ao serviço externo, e quando o evento ocorre, esse serviço faz uma requisição HTTP POST para sua URL com os dados do evento no corpo (payload). Seu sistema recebe a requisição, processa os dados e age de acordo. Sem polling, sem espera, sem requests desnecessários.
Como Funciona
O ciclo de vida de um webhook segue etapas bem definidas:
- Registro: você cadastra sua URL de webhook no serviço externo (ex: Stripe, GitHub, Hotmart)
- Evento ocorre: um pagamento é aprovado, um commit é feito, uma venda é realizada
- Notificação enviada: o serviço externo faz POST na sua URL com o payload JSON do evento
- Processamento: seu sistema recebe, valida a autenticidade e processa os dados
- Resposta: seu sistema retorna HTTP 200 para confirmar o recebimento
- Ação: seu sistema executa a lógica de negócio correspondente
Um payload típico de webhook de pagamento aprovado pode parecer:
{
"event": "payment.approved",
"transaction_id": "TXN-BR-98765",
"customer": {
"name": "João Silva",
"email": "joao@exemplo.com.br",
"cpf": "***.***.***-**"
},
"amount": 299.90,
"currency": "BRL",
"timestamp": "2026-03-22T14:30:00-03:00"
}
Boas práticas de segurança incluem validar a assinatura (signature) que acompanha o payload — um hash criptográfico que prova que o request veio de fato do serviço externo, não de um atacante.
Exemplo Prático
Uma academia de cursos online em Porto Alegre usa webhooks para criar uma experiência de onboarding automatizada e personalizada. O fluxo funciona assim:
Quando um aluno compra um curso na Hotmart, um webhook é disparado para o OpenClaw com os dados da compra. O OpenClaw processa o evento e executa automaticamente:
- Acessa o perfil do aluno no banco de dados
- Cria conta no sistema de EAD e envia credenciais por email
- Envia mensagem de boas-vindas personalizada no WhatsApp com link de acesso
- Agenda uma sequência de mensagens de acompanhamento nos dias seguintes
- Registra o aluno no grupo de WhatsApp da turma correspondente
Tudo isso acontece em menos de 30 segundos após a aprovação do pagamento, sem intervenção humana. A empresa reduziu o tempo de onboarding de horas (quando dependia de processos manuais) para segundos, e relata aumento na satisfação do aluno por ter acesso imediato ao que comprou.
Importância para Empresas
Webhooks são a espinha dorsal da automação empresarial moderna. Praticamente todo serviço SaaS relevante no mercado — Stripe, PagSeguro, Mercado Pago, Shopify, VTEX, HubSpot, Salesforce, GitHub, Jira — oferece webhooks. A capacidade de conectar esses serviços e criar fluxos automatizados que reagem a eventos em tempo real é o que distingue operações modernas e eficientes de processos manuais.
Para empresas brasileiras, os casos de uso mais comuns incluem: automação pós-venda (envio de NF, boas-vindas, suporte), gestão de inadimplência (alertas e cobrança automática quando pagamento falha), sincronização de estoque (webhook de pedido dispara atualização no ERP), e notificações operacionais (webhook de alerta de sistema dispara comunicação para o time via WhatsApp ou Slack).
O retorno sobre investimento de implementar webhooks é geralmente alto. Um processo manual de processamento de pedidos que leva 15 minutos por pedido, quando automatizado via webhooks, custa millisegundos de processamento. Em escala, isso representa horas de trabalho humano economizadas por dia — e erros humanos eliminados do processo.
Webhook no OpenClaw
O OpenClaw funciona tanto como consumidor quanto como produtor de webhooks. Como consumidor: você pode configurar endpoints no OpenClaw para receber webhooks de qualquer serviço externo e definir o que o assistente deve fazer quando cada tipo de evento é recebido. Como produtor: o OpenClaw pode disparar webhooks para sistemas externos quando eventos específicos acontecem nas conversas (mensagem recebida, skill executada, usuário identificado).
A configuração de webhooks no OpenClaw não exige código — você define via interface quais URLs receber, como autenticar os requests, e qual fluxo de automação deve ser ativado para cada tipo de evento. Webhooks de pagamento podem disparar onboardings; webhooks de CRM podem atualizar o contexto do assistente com dados do cliente; webhooks de sistema de monitoramento podem alertar a equipe via WhatsApp automaticamente.
Termos Relacionados
Perguntas Frequentes
Qual a diferença entre webhook e API? API é um contrato para comunicação onde o cliente faz requisições e o servidor responde (pull). Webhook é uma notificação proativa onde o servidor avisa o cliente quando algo acontece (push). Webhooks são ideais para eventos assíncronos; APIs são ideais para consultas e comandos síncronos. Os dois são complementares.
O que acontece se meu servidor estiver offline quando um webhook chega? A maioria dos serviços implementa retry automático: tenta novamente após 1 minuto, 5 minutos, 30 minutos, e assim por diante. Você precisa responder HTTP 200 para confirmar recebimento; se não responder, o webhook é enviado novamente. Sempre implemente idempotência para não processar o mesmo evento duas vezes.
Como proteger meu endpoint de webhook de abusos?
Valide a assinatura do webhook (fornecida pelo serviço como header, ex: X-Stripe-Signature). Implemente rate limiting. Valide o formato do payload antes de processar. Liste os IPs do serviço nas regras de firewall se possível. Nunca execute ações críticas baseadas em webhooks não validados.
Preciso de IP fixo para receber webhooks? Não necessariamente. Qualquer URL publicamente acessível funciona — incluindo URLs geradas por serviços como ngrok (para desenvolvimento local) ou qualquer hospedagem cloud. O serviço externo só precisa conseguir fazer HTTP POST para sua URL.
Webhooks funcionam em tempo real? Quase. A latência depende do tempo de processamento do serviço que dispara e da latência de rede. Tipicamente, webhooks chegam em 1-5 segundos após o evento. Para casos que exigem reação em milissegundos, WebSockets ou Server-Sent Events são alternativas mais adequadas.