Manual
Cadastro direto
Use Leads → Novo lead para conversas, indicações ou formulários sem integração.
Manual visual · gestão de tráfego
Do anúncio ao lead, sem perder o fio.
Organize clientes e campanhas, receba contatos no CRM e acompanhe o atendimento. Para formulários externos, conecte o backend da landing page ao endpoint seguro da plataforma.
O que a integração entrega
1 fluxo
Do envio do formulário ao lead no pipeline da campanha.
- Menos cadastro manual e planilhas
- Campanha e cliente associados ao lead
- Eventos rastreáveis e processados em fila
02 · Entrada
Origens diferentes, mesmo CRM
Leads podem ser cadastrados, importados ou recebidos por integração. A origem e a campanha ajudam a equipe a organizar o atendimento.
Arquivo
Importação CSV
Útil para histórico ou exportações. Revise o mapeamento e a prévia.
Automático
Webhook ou formulário
Uma integração envia o evento; o sistema registra, enfileira e processa o lead.
1
Lead enviadocadastro, webhook ou formulário2
Campanha vinculadaidentifica cliente responsável3
Evento processadovalidação e fila4
CRM atualizadolead chega como “Novo”Importante: receber leads não lança métricas de investimento, cliques ou conversões. UTMs e identificadores podem ficar nas observações, mas não geram atribuição automática.
03 · Vínculo
Prepare a estrutura antes de integrar
A campanha existente é a referência para encaminhar leads do formulário próprio.
Ordem recomendada
Cadastre o cliente
Crie o cliente que será dono dos contatos.
Crie a campanha
Associe-a ao cliente e anote seu campanha_id.
Escolha a origem
O canal organiza a campanha; não é necessário cadastrar nele a URL da landing page.
Valide um envio
Confira o evento em /admin/webhooks e o lead no pipeline.
Estados do CRM
Novoacabou de entrar
Contatadoprimeiro contato feito
Propostaproposta enviada
Convertidovirou cliente
Perdidomotivo registrado
Abra o lead para registrar interações. Cada movimentação no Kanban cria uma interação automática.
04 · Canais de mídia
Google Ads e Meta Ads
O sistema expõe endpoints. O emissor precisa enviar eventos no formato e com autenticação esperados pela integração.
Endpoint Google
Configure o emissor
/webhooks/google não é um campo de URL de landing page nem substitui a configuração de conversões do Google Ads.
Envie os identificadores
O processador espera gclid e cliente_id para criar um lead novo. Sem gclid, o evento não cria lead.
Proteja a origem
WEBHOOK_GOOGLE_SECRET=seu-segredo
WEBHOOK_ALLOW_UNSIGNED=false
WEBHOOK_ALLOW_UNSIGNED=false
Pontos de atenção
Um evento recebido não garante criação do lead: os identificadores exigidos pelo processador precisam estar presentes.
Não confunda os fluxos: formulário externo próprio usa o conector da seção seguinte.
Monitore em /admin/webhooks e /admin/fila.
Endpoint Meta
Verifique o callback
GET /webhooks/meta responde à validação com hub.mode, hub.verify_token e hub.challenge.
Encaminhe eventos
O processador espera leadgen_id e cliente_id para criar um lead novo.
Configure segredos privados
WEBHOOK_META_SECRET=seu-segredo
WEBHOOK_META_VERIFY_TOKEN=seu-token
WEBHOOK_ALLOW_UNSIGNED=false
WEBHOOK_META_VERIFY_TOKEN=seu-token
WEBHOOK_ALLOW_UNSIGNED=false
Recepção e processamento
GET de verificação e POST de evento têm finalidades distintas. Confirme no painel se o job criou o lead.
Se o provedor exigir buscar dados adicionais ou transformar o payload, isso precisa ser feito pelo conector que encaminha os dados.
TikTok, Instagram e outros
Use um conector compatível ou fluxos manuais
Um canal disponível na campanha não significa que exista webhook para esse provedor. Até haver integração específica, use CSV ou cadastro manual; não presuma que o provedor pode enviar diretamente a qualquer endpoint.
05 · Formulário externo
Conecte sua landing page ao CRM
Mantenha a experiência e os campos do seu site, encaminhando os envios à plataforma sem digitação manual.
Informar só a URL não basta. O canal Ads não consulta a landing page. O backend do site ou uma função serverless deve enviar os dados a
POST /integracoes/leads.Backend
Servidor intermediário
Recebe o formulário e faz a chamada server-to-server. Um formulário estático não deve conter o segredo.
Vínculo
Campanha existente
Envie o campanha_id; o sistema deriva da campanha o cliente e usuário proprietários.
Segurança
HMAC e timestamp
Assine o corpo JSON bruto com FORMULARIO_SECRET. O timestamp Unix atual vai no JSON.
1
Visitante enviapreenche o formulário2
Backend assinasegredo privado no servidor3
Plataforma enfileiraPOST /integracoes/leads4
Lead no CRMapós o worker processarCampos obrigatórios
event_typelead_form_submit
idúnico por envio
timestampUnix em segundos
campanha_idcampanha existente
nomenome do contato
Exemplo de payload
{
"event_type": "lead_form_submit",
"id": "form-uuid-unico",
"timestamp": 1791484800,
"campanha_id": 42,
"nome": "João Silva",
"email": "joao@example.com",
"telefone": "11999990000",
"utm_source": "google",
"utm_medium": "cpc"
}
"event_type": "lead_form_submit",
"id": "form-uuid-unico",
"timestamp": 1791484800,
"campanha_id": 42,
"nome": "João Silva",
"email": "joao@example.com",
"telefone": "11999990000",
"utm_source": "google",
"utm_medium": "cpc"
}
Header: X-Formulario-Signature: sha256=<hex>. Consulte o guia técnico para gerar a assinatura.
Configuração
Guarde o segredo
Use o mesmo FORMULARIO_SECRET no `.env` e no backend. Nunca o exponha no navegador.
Envie com segurança
Use HTTPS, assine exatamente o JSON enviado e reutilize o mesmo id em tentativas repetidas.
Mantenha o worker ativo
HTTP 202 confirma recebimento e enfileiramento; o lead é criado depois na fila `webhooks`.
Respostas principais
202recebido e enfileirado
200duplicado processando/processado
401assinatura ou timestamp inválido
422JSON ou campos inválidos
Se não aparecer após 202, confira `/admin/webhooks`, o erro do evento e o worker.
UTMs,
gclid, fbclid e mensagem podem ficar nas observações para consulta. Não atualizam automaticamente métricas nem atribuição de conversões.Passo a passo e exemplo server-side: guia técnico do conector.
06 · Operação
O que acontece depois do POST
A fila separa recepção da criação do lead. A resposta é rápida, mas exige worker ativo e monitoramento.
Recepção
1. Validar e registrar
O controller valida campos e timestamp; o serviço confere HMAC, registra evento e agenda job.
Processamento
2. Executar na fila
O worker processa a fila `webhooks` e retenta falhas transitórias.
Resultado
3. Conferir o CRM
O job cria o lead ou registra erro. HTTP 202 não significa que o processamento terminou.
Comandos
php bin/console queue:once webhooks
php bin/console queue:work webhooks
php bin/console queue:status
php bin/console queue:work webhooks
php bin/console queue:status
Monitoramento
Eventos/admin/webhooks
Fila/admin/fila
Saúde/health
07 · Rotina
Transforme leads em ação
A integração automatiza a entrada; atendimento e análise de desempenho continuam com a equipe.
Diário
Atenda contatos
Abra leads novos, faça o primeiro contato e registre interações.
Semanal
Atualize o pipeline
Mova os cards e registre propostas, conversões ou motivos de perda.
Periódico
Revise as métricas
Lance ou importe dados de mídia separadamente; leads recebidos não preenchem métricas de campanha.
Regra prática: use o `campanha_id` correto e confira cliente e campanha antes do atendimento.
08 · Antes de produção
Checklist de integração
O progresso fica salvo neste navegador.
Configuração
Teste ponta a ponta