Webhooks são o segredo dos negócios que escalam sem código. Enquanto a maioria dos marketers ainda copia e cola dados entre sistemas, empresas modernas usam webhooks para sincronizar automáticamente. Um novo lead no formulário → Mautic recebe → Slack notifica → CRM atualiza. Tudo em segundos, sem trabalho manual.
Mas como webhooks realmente funcionam? E como você começar hoje? Este guia desmistifica o conceito e fornece exemplos prontos para implementar.
- O que é: Uma API “reversa” que empurra dados quando algo acontece
- Diferença vs API: Você puxa dados de uma API; webhook puxa para você
- Uso real: Novo lead → webhook envia para CRM, Slack, Zapier
- Segurança: Assinatura HMAC garante que dados vieram da fonte esperada
- Teste: webhook.site oferece teste grátis e instantâneo
O que é um Webhook?
Webhook é um callback (chamada de volta) que um sistema A faz para um sistema B quando algo acontece no sistema A.
| Conceito | Webhook | API Tradicional |
|---|---|---|
| Direção | Empurra (push) | Puxa (pull) |
| Quando funciona | Quando evento acontece | Quando você pergunta |
| Latência | Quase instantânea | Depende da frequência de polling |
| Eficiência | Alta (sem requisições desnecessárias) | Baixa (muitas requisições em vão) |
| Exemplo | GitHub envia para Slack quando código é pushed | Você pergunta a GitHub a cada minuto: houve push? |
Anatomia de um Webhook
Parte 1: URL do Webhook (O “Endereço”)
Quando algo acontece, o sistema manda dados para uma URL específica. Exemplo:
https://seu-site.com/webhooks/leads
Essa URL é um endpoint que recebe dados em tempo real.
Parte 2: Payload (O “Conteúdo”)
Dados enviados pelo webhook em formato JSON:
{
“event”: “lead.created”,
“timestamp”: “2026-03-31T10:30:00Z”,
“data”: {
“lead_id”: 12345,
“email”: “joao@empresa.com”,
“name”: “João Silva”,
“source”: “landing-page”
}
}
Parte 3: Assinatura (Segurança)
Um HMAC (código criptográfico) prova que webhook veio da fonte esperada:
X-Mautic-Webhook-Signature: sha256=abc123def456…
Seu sistema verifica: se assinatura bate, webhook é confiável.
Webhooks na Prática: 5 Exemplos Reais
Exemplo 1: Novo Lead no Formulário → Mautic
Cenário: Visitante preenche seu formulário no WordPress. Você quer que Mautic saiba automáticamente.
Fluxo:
- Visitante clica “Enviar”
- WordPress dispara webhook: POST https://seusite.com.br/mautic-webhook
- Payload inclui: email, nome, formulário
- Seu servidor valida assinatura
- Mautic API é chamada para criar/atualizar lead
- Lead entra automaticamente em drip campaign
Exemplo 2: Email Clicado em Mautic → Notifica Slack
Cenário: Quando um lead abre seu email em Mautic, você quer notificação instantânea no Slack.
Setup:
- Mautic → Admin → Webhooks
- Novo webhook: URL = https://hooks.slack.com/services/YOUR/WEBHOOK/URL
- Trigger: “Email Aberto”
- Payload customizado: “{lead} abriu email às {timestamp}”
- Salvar
Resultado: Seu time no Slack vê: “João da TechCorp abriu seu email às 15:45”
Exemplo 3: Pagamento Recebido → Atualizar Status no CRM
Cenário: Você usa Stripe para pagamentos. Quando um cliente paga, CRM deve atualizar status automáticamente.
Fluxo:
- Cliente paga R$ 1.000 no Stripe
- Stripe dispara webhook payment_intent.succeeded
- Seu servidor recebe: customer_id, valor, data
- CRM API é chamada: “Marcar cliente como pagador”
- Dashboard atualiza em tempo real
- Email automático dispara: “Pagamento confirmado, obrigado!”
Exemplo 4: Novo Pedido em Shopify → Notifica WhatsApp
Cenário: Integração e-commerce + comunicação. Novo pedido → mensagem WhatsApp para você.
Setup com n8n:
- Shopify envia webhook para n8n: novo pedido
- n8n recebe e processa payload
- Twilio integrado em n8n envia SMS/WhatsApp
- Sua mensagem: “Novo pedido de R$ 500 de {customer}. Prepare para envio!”
Exemplo 5: Lead Deletado no CRM → Remove de Mautic (GDPR)
Cenário: Compliance GDPR. Se alguém pede para remover dados do CRM, Mautic também deve deletar.
Fluxo:
- CRM recebe solicitação de deleção
- CRM dispara webhook: DELETE /mautic/leads/12345
- Mautic valida assinatura e deleta lead
- Logs registram deleção para auditoria
Testando Webhooks: webhook.site
Antes de implementar de verdade, teste seu webhook:
Passo 1: Acesse webhook.site (gratuito, sem cadastro)
Passo 2: Copie a URL gerada (ex: https://webhook.site/a1b2c3d4…)
Passo 3: Configure isso como seu webhook em Mautic, Stripe, etc.
Passo 4: Dispare o evento (preencha formulário, faça pagamento)
Passo 5: webhook.site mostra o payload em tempo real. Veja exatamente o que foi enviado.
Isso economiza horas de debugging. Recomendado 100% antes de implementar.
Segurança: Verificando Assinatura
Qualquer pessoa pode enviar um POST fake para sua URL webhook. Como garantir que veio de Mautic?
Resposta: Assinatura HMAC-SHA256
Como funciona:
- Mautic tem uma “chave secreta”: abc123secret
- Mautic calcula: HMAC-SHA256(payload, abc123secret)
- Mautic envia no header: X-Mautic-Signature: def456hash…
- Seu servidor valida: calcule HMAC local, compare com header
- Se bate, webhook é legítimo. Se não bate, descarte.
Código Python para validar:
import hmac, hashlib
secret = “abc123secret”
payload = request.body
expected = hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()
received = request.headers.get(“X-Mautic-Signature”)
if expected == received:
# Webhook é legítimo
else:
# Rejeitar
Melhores Práticas em Webhooks
1. Sempre Responda 200 OK Rapidamente
Webhook espera resposta em 5-10 segundos. Se sua lógica é lenta, processe em background:
- Receba webhook
- Valide assinatura
- Responda 200 OK IMEDIATAMENTE
- Processe em job assíncrono (fila, celery, etc)
2. Implemente Retry Logic
Se sua URL cair, Mautic tentará reenviar (geralmente 3-5 tentativas).
3. Registre Tudo
Crie logs de webhooks para debugging:
[2026-03-31 10:30:00] Webhook recebido: event=lead.created, lead_id=12345
[2026-03-31 10:30:00] Assinatura validada: OK
[2026-03-31 10:30:01] Mautic API chamada: sucesso
4. Teste em Staging Primeiro
Sempre configure webhook em ambiente de teste antes de produção.
5. Versione Sua Integração
Se payload muda, versione: /webhooks/v1/leads, /webhooks/v2/leads. Permite evolução sem quebrar integrações antigas.
Comparação: Webhooks vs Polling vs API
| Método | Latência | Custo | Complexidade | Melhor Para |
|---|---|---|---|---|
| Webhook | < 1s | Baixo | Média | Eventos críticos em tempo real |
| Polling | Minutos | Alto | Baixa | Sincronização nightly/batch |
| API Manual | Por demanda | Variável | Variável | Consultas pontuais |
Integrando Webhooks com n8n + Mautic
Para lógica mais complexa, combine webhooks + n8n:
- Mautic dispara webhook → n8n recebe
- N8n aplica lógica customizada
- N8n conecta com múltiplos sistemas (Slack, CRM, IA)
- Resultado volta para Mautic se necessário
Exemplo: Lead entra em Mautic → webhook dispara n8n → n8n verifica score do lead → se score > 7, dispara Slack + agenda call
Próximos Passos
Implemente seu primeiro webhook este mês. Comece simples: novo lead em Mautic → webhook → seu email pessoal. Teste com webhook.site. Depois expanda para automações mais complexas com n8n.
Perguntas Frequentes (FAQ)
O que fazer se meu servidor estiver offline quando webhook chegar?
Bom webhook systems implementam retry (tentam novamente 3-5 vezes). Logs do webhook mostram falhas. Se padrão, Mautic pode pausar webhooks. Configure monitoring para alertar quando webhooks falham.
Quantos webhooks posso configurar?
Ilimitado em teoria. Mas cada webhook usa recursos. Recomendação: máximo 10-20 webhooks ativos por instância Mautic. Se mais, considere consolidar com n8n.
Webhook é mais seguro que API?
Não inerentemente. Ambos devem usar HTTPS + autenticação. Webhook tem vantagem: assinatura HMAC prova origem. Certifique-se de validar sempre.
Posso testar webhook em localhost?
Não direto (Mautic em nuvem não alcança seu localhost). Solução: ngrok (túnel público para localhost) ou implemente em servidor temporário para testes.
Como debugar se webhook não está funcionando?
1) webhook.site para capturar payload. 2) Logs do servidor recebedor. 3) Verificar assinatura (print do header + payload). 4) Testar com curl manualmente. 5) Confirmar URL está correta em Mautic.
