Manual
Cadastro direto
Use Leads → Novo lead quando a origem veio de uma conversa, indicação ou formulário que ainda não tem integração.
Manual visual · gestão de tráfego
Do anúncio ao lead, sem perder o fio.
Configure seus canais, conecte cada campanha ao cliente certo e acompanhe o caminho do lead até o CRM. Um guia direto para colocar a operação em funcionamento.
Aha moment
15 min
é a meta para sair do primeiro acesso com cliente, campanha e diagnóstico concluídos.
- Cliente + campanha bem vinculados
- Origem identificada sem retrabalho
- Fila monitorada e segura
02 · Entrada
Três portas para o mesmo funil
O lead pode nascer dentro do sistema ou chegar de um canal externo. A regra é a mesma: identificar a origem, ligar ao cliente e, quando possível, à campanha.
Arquivo
Importação CSV
Ideal para cargas históricas ou exportações. Para métricas, a campanha precisa ter o mesmo nome do CSV; revise a prévia antes de confirmar.
Automático
Webhook
Google Ads e Meta Ads enviam eventos para uma URL. O sistema valida, enfileira, processa e cria ou atualiza o lead.
1
Evento nasceformulário, anúncio ou cadastro2
Identidade resolvecliente e campanha3
Sistema recebevalida e registra4
CRM trabalhapipeline + interações03 · Vínculo
O mapa do lead
Antes de ligar qualquer canal, cadastre o “onde” e o “por quê”. Isso é o que permite analisar origem, custo e conversão.
Ordem recomendada
Cadastre o cliente
Nome único por usuário; segmento, cidade, contato e site são opcionais.
Crie a campanha
Escolha cliente, canal, nome, objetivo, orçamento e status. O canal é obrigatório.
Defina a origem
Use Google Ads, Meta Ads, TikTok Ads, Instagram ou Outro conforme o ponto de entrada real.
Valide o primeiro evento
Confirme no painel de webhooks e no Kanban se o lead caiu em “Novo”.
Estados do CRM
Novoacabou de entrar
Contatadoprimeiro contato feito
Propostaproposta enviada
Convertidovirou cliente
Perdidomotivo registrado
Cada movimentação no Kanban registra uma interação automática. Abra o lead para adicionar ligação, e-mail, reunião, WhatsApp ou nota.
04 · Canais Ads
Configure a origem certa
Selecione um canal para ver o roteiro correspondente. Os endpoints abaixo são os definidos no projeto; segredos ficam apenas no `.env`.
Webhook Google
1. Prepare a campanha
Cadastre cliente e campanha no Gestão de Tráfego. Use um nome que a equipe reconheça e mantenha o objetivo “Leads” quando a conversão for o foco.
2. Aponte o evento
Na configuração de conversões/offline do Google Ads, envie o evento para:
POST https://seudominio.com.br/webhooks/google
3. Proteja o segredo
Preencha no `.env` e mantenha a assinatura HMAC habilitada em produção.
WEBHOOK_GOOGLE_SECRET=seu-segredo
WEBHOOK_ALLOW_UNSIGNED=false
4. Faça um teste
Envie um evento com `event_type`, `gclid`, `cliente_id` e dados do lead. Verifique `/admin/webhooks` e depois `/leads`.
Contrato mínimo
Payload local de teste documentado:
curl -X POST http://localhost/gestao-trafego/webhooks/google \\
-H "Content-Type: application/json" \\
-d '{"event_type":"conversion","gclid":"abc123","cliente_id":1,"full_name":"Teste"}'
Somente desenvolvimento: o teste sem assinatura depende de `WEBHOOK_ALLOW_UNSIGNED=true`. Nunca leve essa configuração para produção.
Meta Lead Ads
1. Crie o formulário
No Meta Business, configure o formulário instantâneo com os campos que o time comercial realmente usa.
2. Configure a verificação
Cadastre a URL de callback e o token de verificação:
GET https://seudominio.com.br/webhooks/meta
hub.mode=subscribe
hub.verify_token=...
hub.challenge=...
3. Receba eventos
Use a mesma rota para POSTs de novos leads. O sistema valida HMAC, registra o evento e envia para a fila `webhooks`.
4. Confira a deduplicação
Reenvios com a mesma origem e `id_externo` não devem criar lead duplicado.
Variáveis necessárias
WEBHOOK_META_SECRET=seu-segredo
WEBHOOK_META_VERIFY_TOKEN=seu-token
WEBHOOK_ALLOW_UNSIGNED=false
A verificação GET usa `hub.challenge`; os eventos POST usam assinatura e entram no mesmo fluxo de processamento assíncrono.
Canal ainda sem webhook documentado
Use cadastro manual ou uma ponte CSV
O projeto lista TikTok Ads, Instagram e Outro como canais de campanha, mas os webhooks documentados são Google e Meta. Até existir um contrato específico, exporte os dados do canal e importe pelo fluxo suportado, ou cadastre o lead manualmente mantendo a origem preenchida.
Não invente um endpoint: o vínculo correto é mais importante que uma automação parcial. Registre a origem real e solicite ao admin a evolução do conector.
05 · Bastidores
O que acontece depois do POST
A fila desacopla a chegada do evento do trabalho de criar ou atualizar o lead. Isso evita que o canal externo fique esperando o processamento completo.
Recepção
1. Validar
O controller confere JSON, origem, assinatura HMAC e grava o evento em `webhook_eventos` com status recebido.
Processamento
2. Enfileirar
O `ProcessarWebhookJob` entra na fila `webhooks`. O worker aplica retry de 30s, 60s, 120s, 240s e 480s.
Resultado
3. Atualizar CRM
O job cria ou atualiza o lead, muda o status do evento para processado/erro e deixa rastreabilidade para operação.
Comandos
php bin/console queue:once webhooks
php bin/console queue:work webhooks
php bin/console queue:status
Pontos de monitoramento
Eventos/admin/webhooks
Fila/admin/fila
Saúde/health
Deduplicaçãoorigem + id_externo
06 · Depois da entrada
Transforme dados em ação
Lead recebido é o começo. A rotina recomendada fecha o ciclo entre aquisição, comercial e otimização.
Diário
Lance ou importe métricas
Investimento, impressões, cliques, leads, vendas e receita. Valide a coerência: cliques ≤ impressões, leads ≤ cliques, vendas ≤ leads.
Semanal
Mova o pipeline
Arraste os cards conforme o funil avança e registre interações com descrição não vazia.
Mensal
Gere o relatório
Escolha cliente e período de até 1 ano. O snapshot é imutável até você pedir “Atualizar dados”.
Regra prática: se o score do diagnóstico estiver abaixo de 60, resolva as recomendações de alta prioridade antes de aumentar orçamento.
07 · Antes de colocar em produção
Checklist de lançamento
Marque o que já foi conferido. O progresso fica salvo neste navegador para você retomar depois.
Configuração
Teste de ponta a ponta