Para enviar dados via webhook para a Laiki, a sua ferramenta faz um POST com um JSON contendo duas entidades: o lead (a pessoa) e o evento (a ação que aconteceu). No evento, três campos são obrigatórios: name, date e externalSource. No lead, basta um identificador entre e-mail, telefone e externalId. Este tutorial lista todos os campos aceitos, explica como a Laiki identifica cada lead e mostra por que nenhum evento entra duplicado, mesmo quando a ferramenta reenvia o mesmo disparo.
Vale para qualquer sistema capaz de disparar um payload (o pacote de dados) em JSON: CRM, plataforma de automação, formulário de site, chatbot ou um sistema próprio da sua empresa. Se quiser guardar esta referência, no fim do artigo tem um PDF com as tabelas para baixar e compartilhar com o time.
Como o envio funciona, passo a passo
1. A ferramenta dispara o webhook. A cada ação combinada (novo lead, conversão, mudança de etapa), a ferramenta de origem envia um POST com os dados em JSON para o endereço do workflow.
2. A Laiki recebe o payload. O workflow lê os campos do JSON e organiza o que é dado da pessoa e o que é dado da ação.
3. Lead e evento são gravados. O workflow cria o lead (ou atualiza, se ele já existir na base) e registra o evento — pronto para segmentações, dashboards, relatórios e consultas por agente de IA, já que a Laiki é um software agêntico com dados acessíveis via MCP.
Esse é o caminho completo de quem decide enviar dados via webhook para a Laiki. Quem monta o workflow somos nós; o que a sua ferramenta precisa garantir é só o conteúdo do envio, e é disso que tratam as duas tabelas a seguir.
Campos da entidade Lead
A entidade Lead carrega os dados da pessoa. Nenhum campo aqui é obrigatório de forma isolada, mas há uma regra de identificação logo abaixo da tabela.
| Campo | Tipo | Para que serve |
|---|---|---|
| name | texto | Nome do lead |
| texto | E-mail principal | |
| phone | texto | Telefone principal |
| company | texto | Empresa do lead |
| jobTitle | texto | Cargo na empresa |
| tags | texto | Etiquetas para organizar o lead (origem, produto de interesse) |
| notes | texto | Observações livres |
| externalId | texto | ID do lead na ferramenta de origem, para cruzar as duas bases |
| createdAt | texto (data) | Data de criação do lead na ferramenta de origem |
Regra prática: envie tudo o que a ferramenta de origem tiver. Cada campo preenchido melhora as segmentações e os relatórios que saem do outro lado.
Como a Laiki identifica o lead
A identidade do lead é composta por e-mail, telefone e/ou externalId: basta UM deles em cada envio, não os três. É por esse identificador que a Laiki reconhece a pessoa. Identificador já existente na base? O evento entra no lead que já está lá e o cadastro é atualizado. Identificador inédito? Um lead novo é criado — e é isso que impede cadastros duplicados da mesma pessoa.
Um envio sem nenhum dos três não tem a quem pertencer, então garanta pelo menos um deles no payload.
Guia de prompts para marketing e vendas
Aqui você encontra 70 prompts com perguntas sobre marketing, vendas e comportamento para fazer aos seus dados! Gere insights e usando o MCP da Laiki conectado ao seu Agente de IA.
Campos da entidade Event
A entidade Event descreve a ação: o preenchimento do formulário, a mudança de etapa, a compra. Aqui existem três campos obrigatórios, marcados na tabela.
| Campo | Tipo | Obrigatório? | Para que serve |
|---|---|---|---|
| name | texto | Sim | Nome do evento (formulario_contato, lead_qualificado) |
| date | texto (data/hora) | Sim | Data e hora em que o evento aconteceu |
| externalSource | texto | Sim | Origem do dado (o nome da ferramenta que envia) |
| value | número | Não | Valor monetário associado, quando houver |
| url | texto | Não | URL da página onde o evento ocorreu |
| domain | texto | Não | Domínio do site |
| device | texto | Não | Dispositivo do visitante (mobile, desktop) |
| source | texto | Não | Canal ou fonte do evento |
| identifier | texto | Não | Identificador livre do evento |
| externalId | texto | Não | ID do evento na ferramenta de origem |
| utmSource | texto | Não | UTM de origem da campanha |
| utmMedium | texto | Não | UTM de mídia da campanha |
| utmCampaign | texto | Não | UTM de nome da campanha |
| utmContent | texto | Não | UTM de conteúdo do anúncio |
| utmTerm | texto | Não | UTM de termo ou palavra-chave |
| utmChannel | texto | Não | Canal consolidado da campanha |
Sem name, date e externalSource, o evento não é registrado. Os seis campos de UTM merecem atenção especial: são eles que alimentam a atribuição de canal. Sempre que a informação de campanha existir na ferramenta de origem, vale enviar.
Idempotência: por que o mesmo evento nunca entra duas vezes
Webhooks falham na prática: a rede oscila, a ferramenta não recebe a confirmação e reenvia o mesmo disparo. Se cada reenvio virasse um evento novo, as contagens de conversão inflariam e o funil passaria a mentir.
Idempotência é a garantia de que repetir a mesma operação produz o mesmo resultado de uma execução única — conceito da própria especificação HTTP, documentado no glossário da MDN Web Docs. Na Laiki, cada evento carrega uma chave de idempotência gerada do nosso lado, a partir dos dados do próprio envio (identificador do lead, nome do evento, data). Chegou uma chave que já foi gravada? O evento não entra de novo. Você não precisa criar nem mandar essa chave: pode reenviar sem medo, a contagem não dobra.
E se a minha ferramenta tiver campos fora da lista?
As tabelas acima cobrem os campos nativos. Quando a ferramenta de origem captura algo que não se encaixa neles, como a resposta de uma pergunta específica do formulário, criamos um campo personalizado na sua conta para receber esse dado, no tipo certo (texto, número, data ou verdadeiro/falso). Basta listar quais campos extras existem no seu payload que a gente prepara a conta antes do primeiro disparo.
Perguntas frequentes
Preciso de programador para enviar dados via webhook?
Na maioria dos casos, não. A maior parte dos CRMs, plataformas de automação e construtores de formulário já tem a opção de disparar webhooks pela própria interface: você cola o endereço, escolhe o gatilho e mapeia os campos. Programação só entra quando o envio parte de um sistema próprio da sua empresa.
Em que formato os dados devem ser enviados?
Em JSON, por uma requisição POST. Os nomes dos campos podem vir do jeito que a sua ferramenta gera: o mapeamento entre o payload dela e os campos da Laiki é feito no workflow, do nosso lado. O que importa é o dado estar presente no envio.
O que acontece se um envio falhar?
Se o disparo não chegar, a maioria das ferramentas tenta de novo automaticamente. E é aí que a idempotência trabalha a seu favor: a ferramenta pode reenviar o mesmo pacote quantas vezes precisar, porque a Laiki reconhece a repetição e grava o evento uma vez só.
Guarde esta referência
Leve esta referência com você. As duas tabelas de campos e o passo a passo do envio em um PDF pronto para compartilhar com o time ou com a ferramenta que vai fazer a integração.
E se você ainda não usa a Laiki e quer parar de perder dados entre uma ferramenta e outra, fale com a gente: montamos o workflow de recebimento junto com você, e quem quiser enviar dados via webhook para a sua operação vai encontrar tudo pronto do outro lado.
