Webhooks de entrada

Um webhook de entrada é um endereço do Leadz que recebe dados de outro sistema: um formulário, uma landing page, uma plataforma de venda ou uma ferramenta de automação. Você cola o endereço no sistema de origem, ele envia os dados em JSON e o Leadz cria ou atualiza o contato. Cada envio também pode iniciar um funil.

#Antes de começar

• Seu cargo precisa ter acesso a Webhooks e Postbacks. Para copiar o endereço completo, é preciso administrar o workspace (a conta da sua empresa dentro do Leadz).
• O sistema de origem precisa enviar um POST com o corpo em JSON. Formulário codificado (application/x-www-form-urlencoded) também é aceito.
• A quantidade de endereços depende do seu plano. Veja em sparkleleadz.com/planos.

#Criar o webhook

Na primeira vez, a tela oferece três atalhos que já abrem o formulário preenchido: Formulário do site, Zapier / Make / SaaS e Conversão afiliados.

#Copiar o endereço

O cartão URL pública · POST mostra o endereço do webhook. Ele já inclui o token que autoriza o envio.

• Na tela, o token aparece escondido. Clique em Mostrar token se precisar conferir.
• Copiar leva sempre o endereço inteiro, com o token.
• Cole o endereço no sistema de origem exatamente como foi copiado.

O formato é este. Use sempre o que a tela mostrar:

https://SEU-ENDERECO/api/webhooks/ID-DA-CONTA/formulario-do-site?token=SEU-TOKEN

#Enviar um teste

Dispare um envio de teste pelo sistema de origem ou pelo terminal:

curl -X POST "https://SEU-ENDERECO/api/webhooks/ID-DA-CONTA/formulario-do-site?token=SEU-TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "nome": "Maria Souza",
    "email": "maria@exemplo.com",
    "telefone": "5511999990000",
    "plano": "anual"
  }'

Resposta de sucesso:

{ "ok": true, "id": "identificador-do-evento" }

O envio aparece em Eventos recebidos. A lista se atualiza sozinha a cada 10 segundos.

#Mapear os campos

Mapear é dizer ao Leadz o que cada campo do JSON significa.

Os destinos ficam em três grupos:

Regras que evitam erro:

• Se você mapear só Telefone, o Leadz usa o mesmo número como WhatsApp do contato.
• Use Valor quando a origem manda 55.00 e Valor em centavos quando manda 5500. Trocar os dois grava um valor 100 vezes maior.
• Se a origem separa o número em DDI, DDD e telefone, mapeie cada parte no destino próprio. O Leadz junta as três.
• As tags não vêm do JSON. Elas são definidas na configuração, em Tags padrão.

#Configurar a partir do evento

Para mapear vários campos de uma vez, abra um evento e clique em Configurar a partir deste evento. A janela lista todos os campos recebidos.

Encontra contato faz o Leadz procurar um contato que já tenha aquele valor antes de criar um novo. Mesmo sem marcar nada, o Leadz procura pelo e-mail, WhatsApp e telefone mapeados. Marque o campo quando a pessoa é identificada por outro dado, como um código da origem.

#Configurar o comportamento

Clique em Configurar no cartão do endereço. Ao terminar, clique em Salvar configuração.

Em Recebimento e segurança ficam os ajustes técnicos: Métodos HTTP aceitos, Content-Types aceitos, Autenticação, Deduplicação — campo do ID do evento e Devolver o id do payload na resposta.

#O que um webhook pode fazer

• Criar ou atualizar o contato, com campos nativos e personalizados, origem e tags.
• Registrar o evento no histórico da ficha do contato, com o nome do webhook.
• Abrir uma negociação, quando um valor é mapeado. Sem Situação mapeada, ela entra como concluída. Veja Checkouts e plataformas.
• Iniciar um funil. No editor de funil, use o gatilho Entrada via webhook e escolha o webhook, ou deixe Qualquer webhook. O bloco Aguardar Evento também pode esperar por um webhook no meio do funil.

O webhook não move o card no quadro do CRM sozinho. Para isso, inicie um funil com o gatilho e use nele um bloco que mova o card.

#Histórico, segurança e limites

• Histórico. O Leadz guarda os 50 eventos mais recentes de cada endereço. O ícone de lixeira em Eventos recebidos limpa a lista sem apagar os contatos já criados.
• Estado de cada evento. Verde é Contato criado ou Contato vinculado. Amarelo é Sem ação no CRM. Vermelho é Falhou ao processar ou Limite de contatos atingido.
• Trocar o token. Gerar novo token invalida o endereço atual na hora. Cole o endereço novo no sistema de origem.
• Assinatura. Em Autenticação, HMAC-SHA256 (corpo assinado) faz o Leadz conferir a assinatura do corpo. Só serve se a origem souber assinar.
• Reenvios. Com Deduplicação — campo do ID do evento preenchido, um reenvio idêntico é aceito, mas não cria contato nem negociação de novo.
• Limite de envio. Cada origem pode enviar até 120 requisições por minuto. Acima disso, a resposta é 429.
• Tamanho. O corpo pode ter até 25 MB com o token no endereço ou no cabeçalho. Com assinatura HMAC, o limite é 1 MB.

#Problemas comuns

A origem recebe erro 401

O envio chegou sem o token ou com o token errado. Copie o endereço de novo pelo botão Copiar e cole inteiro. Um envio recusado não é gravado, por isso não aparece em Eventos recebidos.

Aparece «Contato não foi gravado.» com «Nenhum mapeamento configurado»

O evento chegou, mas nenhum campo foi mapeado. Mapeie pelo menos o Nome.

Aparece «Contato não foi gravado.» e o nome não foi encontrado

O campo mapeado como Nome não veio neste envio ou veio vazio. Abra o evento e confira o caminho do campo.

Aparece «Nenhum contato encontrado pelas regras de vínculo»

O Comportamento está em Só vincular e não existe contato com aquele e-mail ou telefone. Troque para Vincular ou criar se quiser receber contatos novos.

O evento aparece como «Limite de contatos atingido»

O workspace chegou ao limite de contatos do plano. O evento fica guardado, mas o contato não é criado, e a origem recebe o erro 403.

A origem recebe erro 415

O envio veio com um Content-Type que o endereço não aceita. Marque o tipo em Content-Types aceitos.

Cada envio cria um contato duplicado

O Comportamento está em Sempre criar novo, ou o envio não traz nada que identifique a pessoa. O Leadz reconhece o mesmo contato pelo e-mail, WhatsApp ou telefone mapeados e pelos campos marcados em Encontra contato. Mapeie pelo menos um deles.

#Veja também

• Postbacks
• Checkouts e plataformas
• Webhook de saída