Webhook genérico

Esta página tem duas partes. A Parte 1 é para a equipe técnica que vai programar o envio. A Parte 2 é para a imobiliária, que cria a conexão dentro do CRM e vincula os campos.

Seu site não tem quem programe no servidor?

Se a página foi feita em construtor de sites, ou é um WordPress sem acesso ao código, use os Formulários do site do CRM, em Configurações > Conexões > Integrações, seção Seu site. Eles se instalam colando uma linha de código na página e não expõem nenhuma senha. O webhook genérico é para quando o seu servidor envia os dados.

A ordem é esta:

1. A imobiliária cria a conexão (Parte 2, passos 1 a 4) e entrega o endereço e o token.
2. A equipe técnica programa e testa o envio (Parte 1).
3. A imobiliária vincula os campos (Parte 2, passo 5 em diante).

Nota

Na tela, vincular os campos também aparece como mapeamento: é a mesma coisa.

---

Parte 1: para quem programa o envio

Como funciona

1. A imobiliária cria uma conexão no CRM e entrega a você um endereço e um token.
2. A cada lead, o seu servidor faz um POST com um JSON para esse endereço.
3. Quando o primeiro lead chega, a imobiliária vincula os campos do seu JSON aos campos do CRM. Os leads que chegarem antes disso ficam guardados, sem prazo, e entram sozinhos quando o vínculo é salvo.

Regras obrigatórias

O token é uma senha

Só o seu servidor pode conhecer o token: com ele, qualquer pessoa cria leads falsos na imobiliária. Por isso o envio sai sempre do servidor, nunca do navegador, de app de celular ou de programa instalado no computador de alguém.

Regra	Por quê
Envie do servidor. Nunca do navegador, de app de celular ou de programa instalado no computador de alguém.	O token é uma senha. Onde a pessoa tem o código na mão, qualquer um copia o token e cria leads falsos.
Use sempre https:// e deixe a verificação do certificado ligada: nada de curl -k, verify=False, CURLOPT_SSL_VERIFYPEER => false ou rejectUnauthorized: false.	Sem conferir o certificado, quem estiver no caminho se passa pelo CRM e lê o token.
Não siga redirecionamento. Resposta 301, 302, 307 ou 308 quer dizer que o endereço está errado, quase sempre http://. Corrija e peça para gerar um token novo.	Na tentativa por http:// o token já viajou aberto, mesmo que o reenvio para https:// funcione.
Mande o token só no cabeçalho X-Webhook-Token (ou Authorization: Bearer <TOKEN>). Nunca na URL.	URL fica gravada em logs de servidores e proxies, inclusive no seu.
Não grave o token em log. Desligue o log de cabeçalhos do seu cliente HTTP e mascare X-Webhook-Token e Authorization no seu monitoramento.	Log é lido por mais gente e guardado por mais tempo que o código.
Proteja o seu formulário com captcha ou campo isca e limite de envios por IP.	O CRM confia no que o seu servidor manda: spam que passar pelo seu site vira lead e oferta para os corretores.
Envie Content-Type: application/json; charset=utf-8 e o corpo em UTF-8.	Corpo em outra codificação (Latin-1, Windows-1252) é recusado como JSON inválido.
Um lead por requisição, num objeto JSON.	Lista, texto ou número sozinho não vira lead: a resposta é 200, mas o envio fica como Ignorado.
Corpo com até 32 KB, sem arquivos nem base64. Não mande CPF, documento, senha nem dado de cartão.	Um lead de formulário tem poucos KB. O que chega fica guardado como foi recebido.
Guarde do seu lado o lead que for recusado (400, 403, 413, 415).	O CRM não guarda o que recusa. Depois de corrigir, reenvie esses leads.

Rede

• Libere a saída HTTPS (porta 443) para imobiliarcrm.com.br. Use o nome, não o IP: o IP pode mudar.
• O servidor aceita TLS 1.2 ou mais novo.
• Configure 10 segundos de tempo limite. A resposta costuma chegar em menos de 1 segundo.

Endereço e token

POST https://imobiliarcrm.com.br/webhook/api/v1/panels/<ID_DO_PAINEL>/webhooks/generic/<CHAVE_DA_CONEXAO>

Você recebe o endereço pronto da imobiliária, que o copia da tela da conexão. Não monte à mão. No endereço, <ID_DO_PAINEL> é o código da conta da imobiliária no CRM (26 letras e números) e <CHAVE_DA_CONEXAO> começa com c_. Se o endereço que você recebeu termina em /webhooks/generic, sem chave, ele é de uma ligação antiga: peça o endereço de uma conexão nova.

O endereço não é senha; o token é

O token tem 43 caracteres (letras, números, - e _). Copie sem espaço nem quebra de linha no fim, senão a resposta é 403. Mande o token num cabeçalho só: se mandar os dois, vale o X-Webhook-Token.

Exemplo

curl -X POST "https://imobiliarcrm.com.br/webhook/api/v1/panels/<ID_DO_PAINEL>/webhooks/generic/<CHAVE_DA_CONEXAO>" \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "X-Webhook-Token: <TOKEN>" \
  --max-time 10 \
  --data '{
    "id_envio": "site-000123",
    "name": "Maria Souza",
    "email": "maria@example.com",
    "phone": "(51) 99999-0000",
    "message": "Quero visitar o apartamento no sábado.",
    "property_ref": "IM-000123",
    "purpose": "venda",
    "budget_max": 500000,
    "bedrooms": 2
  }'

Resposta esperada: 200 com {"status": "received", "request_id": "..."}. Nos testes, troque o e-mail e o telefone pelos da sua equipe.

Exemplos em outras linguagens

Os dois exemplos fazem o mesmo envio do curl acima: o mesmo corpo, o token só no cabeçalho, 10 segundos de tempo limite, o certificado conferido e sem seguir redirecionamento. O token vem de uma variável de ambiente do seu servidor (aqui, CRM_WEBHOOK_TOKEN), nunca do código.

PHP (extensão curl)

<?php
$url = 'https://imobiliarcrm.com.br/webhook/api/v1/panels/<ID_DO_PAINEL>/webhooks/generic/<CHAVE_DA_CONEXAO>';
$token = getenv('CRM_WEBHOOK_TOKEN');

// Gere o corpo uma vez e guarde: o reenvio manda este mesmo texto.
$corpo = json_encode([
    'id_envio' => 'site-000123',
    'name' => 'Maria Souza',
    'email' => 'maria@example.com',
    'phone' => '(51) 99999-0000',
    'message' => 'Quero visitar o apartamento no sábado.',
    'property_ref' => 'IM-000123',
    'purpose' => 'venda',
    'budget_max' => 500000,
    'bedrooms' => 2,
], JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR);

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $corpo,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json; charset=utf-8',
        'X-Webhook-Token: ' . $token,
    ],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 10,
    CURLOPT_SSL_VERIFYPEER => true,
    CURLOPT_SSL_VERIFYHOST => 2,
    CURLOPT_FOLLOWLOCATION => false,
]);
$resposta = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);

if ($resposta === false) {
    // Erro de rede ou tempo esgotado: reenvie o mesmo $corpo (veja Reenvio).
} elseif ($status !== 200) {
    // Decida pelo código HTTP (veja Respostas) e guarde o lead se ele foi recusado.
}

Node.js (fetch)

Node.js 20 ou mais novo, num módulo ES (arquivo .mjs ou "type": "module").

const url = 'https://imobiliarcrm.com.br/webhook/api/v1/panels/<ID_DO_PAINEL>/webhooks/generic/<CHAVE_DA_CONEXAO>';

// Gere o corpo uma vez e guarde: o reenvio manda este mesmo texto.
const corpo = JSON.stringify({
  id_envio: 'site-000123',
  name: 'Maria Souza',
  email: 'maria@example.com',
  phone: '(51) 99999-0000',
  message: 'Quero visitar o apartamento no sábado.',
  property_ref: 'IM-000123',
  purpose: 'venda',
  budget_max: 500000,
  bedrooms: 2,
});

try {
  const resposta = await fetch(url, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json; charset=utf-8',
      'X-Webhook-Token': process.env.CRM_WEBHOOK_TOKEN,
    },
    body: corpo,
    redirect: 'manual',
    signal: AbortSignal.timeout(10000),
  });
  if (resposta.status !== 200) {
    // Decida pelo código HTTP (veja Respostas) e guarde o lead se ele foi recusado.
  }
} catch (erro) {
  // Erro de rede ou tempo esgotado: reenvie o mesmo corpo (veja Reenvio).
}

Nomes de campo recomendados

Use name, email, phone e message. Com eles, o CRM já sugere o vínculo sozinho e a imobiliária só confere. Também são reconhecidos nome, full_name, telefone, phone_number, mensagem e notes. O reconhecimento é pelo nome exato, em minúsculas e no primeiro nível do JSON. Os outros campos, como property_ref, purpose, budget_max e bedrooms do exemplo, a imobiliária vincula na tela.

O que o CRM sabe receber

Qualquer campo do seu JSON pode ser vinculado a um destes destinos, com o nome que aparece na tela Vincular campos. Campo não vinculado não é gravado no contato nem no lead; ele fica só no envio recebido.

Destino na tela	Formato esperado
Contato: Nome completo, E-mail, Empresa, Cargo, Instagram	Texto, até 255 caracteres. O lead precisa de pelo menos nome, e-mail ou telefone. Sem e-mail nem telefone, o CRM não reconhece quem já é cliente.
Contato: Telefone principal e Telefone secundário	Texto com DDD, até 50 caracteres. Veja Telefone.
Contato: Cidade	Texto, até 100 caracteres.
Contato: Estado	Sigla de 2 letras, como RS. "Rio Grande do Sul" faz o lead falhar.
Contato: Observações e Lead: Observações	Texto livre. Junte do seu lado, num campo só, tudo o que for mensagem.
Lead: Referência do imóvel	O código do imóvel no CRM, como IM-000123, ou o código dele no sistema Imobiliar. Código que não existe no CRM é ignorado sem aviso. Imóvel indisponível (vendido, alugado, reservado) não é ligado, e o lead ganha uma nota dizendo qual imóvel foi pedido e por quê.
Lead: Finalidade	venda ou aluguel. Também valem sale, rent, compra, comprar, vender, alugar, locação e lançamento (que conta como venda). Outro valor não derruba o lead: ele entra sem finalidade.
Lead: Orçamento mínimo e Orçamento máximo	Número com ponto decimal e sem separador de milhar: 500000 ou 500000.00. "500.000" é lido como 500, e "500.000,00" e "R$ 500 mil" são descartados.
Lead: Quartos desejados	Número inteiro, como 2. "2 quartos" é descartado.
Lead: Temperatura	Só hot, warm, cold ou frozen, exatamente assim. Outro valor, como quente, faz o lead falhar. Sem o campo, o lead entra como warm. Se a imobiliária usa a temperatura automática, o CRM recalcula depois.
Campos personalizados (Contato ou Lead)	Veja Campos personalizados.

Não vincule nada ao destino Origem

A imobiliária não deve vincular nada ao destino Origem: ele troca a origem da conexão, e o lead deixa de aparecer como vindo dela nos relatórios e nas regras de distribuição.

Campos personalizados

Use no JSON o nome que quiser, por exemplo "renda_mensal", e combine com a imobiliária a qual campo personalizado ele vai. O campo precisa existir no CRM antes do vínculo: a imobiliária cria em Configurações > Como trabalhamos > Campos personalizados.

Tipo do campo no CRM	Como enviar
Texto, Texto longo, Telefone, CPF, CNPJ	Texto.
Número, Dinheiro (R$)	1500.50, "1500,50" ou "R$ 1.500,50".
Data, Data e hora	"2026-10-22", "2026-10-22T14:30:00" ou "22/10/2026".
Checkbox (Sim/Não)	true, 1 ou "sim" marcam. Qualquer outro valor desmarca.
Seleção única	O texto da opção, exatamente como está cadastrado.
Seleção múltipla	Uma opção só por campo, como texto. Lista não funciona.

Valor que não dá para converter, como uma data em outro formato, é guardado como texto e pode não aparecer na tela.

Formato do JSON

Prefira um JSON sem objetos dentro de objetos e com valores simples: texto, número, verdadeiro ou falso. Objeto dentro de objeto funciona, porque o vínculo usa o caminho, como cliente.nome. Lista aparece na tela como um campo só e é gravada como texto no formato ['a', 'b']; para mandar várias opções, junte num texto, como "Piscina, Churrasqueira". Não use ponto no nome de um campo e não renomeie campos depois do vínculo: campo com nome novo deixa de ser gravado até a imobiliária vinculá-lo de novo.

Telefone

Mande com DDD, com ou sem pontuação: "(51) 99999-0000", "51999990000" ou "+55 51 99999-0000". Sem o 0 na frente do DDD. O CRM guarda no formato +55 seguido do DDD e do número. Número sem DDD fica errado. Número de outro país vai com + e o código do país. O CRM procura a pessoa primeiro pelo e-mail e depois pelo telefone, no principal ou no secundário, com ou sem o 9 e com ou sem o 55.

Respostas

HTTP	Corpo	O que fazer
200	{"status": "received", "request_id": "..."}	O CRM guardou o envio. Veja abaixo o que o 200 garante.
200	{"status": "duplicate", "request_id": "..."}	O mesmo corpo já chegou por esta conexão há menos de 5 minutos. Trate como sucesso e não reenvie.
400	{"detail": "Invalid JSON payload"}	Corpo vazio, JSON inválido ou fora de UTF-8. Corrija antes de reenviar.
400	{"detail": "Send the token in the X-Webhook-Token header"}	Token na URL. Mande no cabeçalho e peça um token novo, porque o antigo ficou exposto.
403	{"detail": "..."}	Token errado ou ausente, token trocado, conexão removida, endereço copiado errado ou envio sem HTTPS. Não reenvie automaticamente: guarde o lead, confira o endereço, peça o token novo e reenvie depois de trocar.
404 ou 405	pode não ser JSON	Endereço errado ou método diferente de POST. Confira o endereço copiado.
413	{"detail": "Payload too large"}	Corpo grande demais. Tire anexos e textos longos.
415	{"detail": "..."}	Content-Type diferente de application/json.
429	{"detail": "..."}	Envios demais para esta conexão em pouco tempo. Espere o tempo do cabeçalho Retry-After e reenvie.
500, 502, 503, 504	pode não ser JSON	Erro do nosso lado ou indisponível por instantes. Reenvie com espera crescente.

Decida pelo código HTTP, não pelo corpo

Algumas respostas de erro vêm em HTML. As recusas 400 de token na URL, 403 sem HTTPS, 415 e 429 fazem parte do contrato e entram em vigor conforme o CRM liga essas proteções; quem segue as regras acima nunca as recebe.

O que o 200 garante

received quer dizer que o CRM guardou o envio. O lead é criado logo depois, em poucos segundos, e o resultado aparece para a imobiliária na aba Eventos recebidos da conexão:

• Processado: virou lead ou foi ligado a um atendimento que já existia;
• Aguardando mapeamento: falta vincular os campos;
• Ignorado: veio sem nome, e-mail e telefone, ou o corpo não é um objeto JSON;
• Falhou: algum valor fora do formato, como temperatura desconhecida, estado com mais de 2 letras ou texto longo demais.

Dica

No começo da integração, confira com a imobiliária se os envios estão como Processado.

Reenvio

• 429 e respostas 5xx: o envio não foi guardado. Reenvie com espera crescente, por exemplo 1, 5, 15 e 60 minutos.
• Erro de rede ou tempo esgotado: você não sabe se o envio chegou. Reenvie exatamente o mesmo corpo em até 5 minutos, por exemplo depois de 30 segundos e de 2 minutos. Se o primeiro tinha chegado, a resposta é duplicate. Passados 5 minutos, o reenvio vira um envio novo; se o contato tem e-mail ou telefone, ele é ligado ao mesmo atendimento e não abre outro lead.
• Nunca reenvie em 400, 403, 404, 413 ou 415 sem corrigir antes: a resposta não muda.
• Depois da última tentativa, guarde o lead num registro do seu lado para reenviar à mão.

O que conta como o mesmo envio: o corpo idêntico, caractere por caractere, para a mesma conexão. Gere o JSON uma vez, guarde o texto e reenvie esse mesmo texto. Não monte o JSON de novo a cada tentativa (a ordem dos campos e os espaços podem mudar) e não coloque no corpo a hora da tentativa. Os cabeçalhos não contam. Dois envios com corpo idêntico em menos de 5 minutos viram um só; por isso inclua um identificador do envio, criado uma vez e repetido nos reenvios, como o id_envio do exemplo.

Identificador da requisição e suporte

Não envie o cabeçalho X-Request-Id. O CRM gera o identificador e devolve no cabeçalho X-Request-Id da resposta; nas respostas 200, ele também vem no corpo, como request_id. Guarde esse código. Se precisar de ajuda, a imobiliária abre o chamado com o suporte do Imobiliar CRM e informa o código.

Se a pessoa já é cliente da imobiliária

O CRM procura a pessoa pelo e-mail e, se não achar, pelo telefone. Se ela já tem um lead em andamento (qualquer etapa antes de convertido, perdido ou reciclado), o CRM não abre lead novo:

• o envio fica ligado ao lead que já existe, e o imóvel de interesse é somado a ele quando está disponível;
• a mensagem, a finalidade, o orçamento, os quartos, a temperatura e os campos personalizados do lead que vieram neste envio não entram no lead e ficam só no envio recebido;
• nome e telefone do contato não mudam; os campos personalizados do contato são atualizados;
• o lead não volta para a distribuição, e o corretor não recebe aviso.

Se o lead anterior já foi convertido, perdido ou reciclado, o envio abre um lead novo. Envio só com nome, sem e-mail e sem telefone, sempre cria um contato novo.

Testar

Não existe ambiente de testes separado

O teste acontece na conta real da imobiliária, e o lead de teste vira lead de verdade assim que os campos são vinculados: entra na distribuição, pode avisar corretores e disparar automações, como mensagem de boas-vindas.

1. Combine o horário com a imobiliária e peça para ela deixar aberta a aba Eventos recebidos da conexão.
2. Monte um JSON com todos os campos que o site vai mandar, todos preenchidos. A tela de vínculo mostra os campos do último envio: campo que não veio no teste não aparece para vincular.
3. Use o nome Teste do site com o e-mail e o telefone da sua equipe, nunca de outra pessoa.
4. A resposta deve ser 200 com "status": "received". O envio aparece como Aguardando mapeamento. Se não aparecer, a imobiliária clica em Atualizar. Envio recusado (4xx) não aparece na lista: confira a resposta HTTP.
5. A imobiliária vincula os campos e salva. O envio passa a Processado e o lead aparece na lista de leads.
6. Para repetir, mude algum texto do corpo: o mesmo corpo em menos de 5 minutos responde duplicate. Com o mesmo e-mail ou telefone, enquanto o primeiro lead estiver aberto, não nasce lead novo.
7. No fim, a imobiliária marca os leads de teste como perdidos.

Cuidados com o token

• O token só serve para criar leads nesta conexão; ele não lê nada do CRM. Mas, com ele, qualquer pessoa cria leads falsos, que entram na distribuição e podem disparar as automações da imobiliária, como WhatsApp e e-mail para o contato do lead.
• Guarde como senha: variável de ambiente ou cofre de segredos. Nunca no código, no git, no JavaScript da página, em print, em chamado, em e-mail ou em grupo de mensagem.
• Use uma conexão por sistema e por ambiente (site, sistema antigo, homologação). Assim, trocar o token de um não derruba os outros, e o teste não cai na conexão de produção.
• Peça um token novo quando houver suspeita de vazamento, quando alguém com acesso sair da equipe ou da agência, ou quando o token tiver ido por http://, numa URL ou para um log. Sem nenhum desses motivos, troque ao menos uma vez por ano.
• A troca não tem período de transição: o token antigo para na hora, e todo envio com ele recebe 403 e não é guardado. Combine o momento com a imobiliária, troque o token no seu servidor logo em seguida e reenvie os leads que receberam 403 nesse intervalo. O endereço continua o mesmo.

---

Parte 2: para a imobiliária, dentro do CRM

Quem pode fazer: o dono ou um administrador do painel (a conta da imobiliária no CRM).

1. Abra Configurações, seção Conexões, item Integrações.
2. Em Outras origens, no cartão Genérico, clique em Criar conexão. Se o painel já tiver conexões, o botão se chama Conexões. Abre a lista de conexões.
   • Se a lista já mostrar uma Conexão original, não a entregue à equipe do site. Ela é de uma ligação antiga e usa outro formato de envio. Crie uma conexão nova. Neste caso, a conexão nova começa com o vínculo de campos da original: abra Vincular campos e confira antes do primeiro envio de verdade.

Nota

Não encontrou o cartão Genérico em Outras origens? Fale com o suporte do Imobiliar CRM.

3. Clique em Nova conexão, preencha o Nome, como “Site institucional”, e clique em Criar. Esse nome vira a origem dos leads e aparece como Genérico: Site institucional nos leads, nos relatórios e nas regras de distribuição. Use um nome curto, de até 40 letras. A origem não muda se você renomear a conexão depois. Crie uma conexão para cada site ou sistema. Se o plano do painel já estiver no limite de conexões genéricas, o CRM avisa e não cria.
4. A conexão abre na aba Endereço e token. Use Copiar endereço e Copiar token e entregue os dois à equipe técnica do site por um canal seguro: um gerenciador de senhas compartilhado, ou o endereço por um canal e o token por outro. Nunca num grupo aberto nem num e-mail com várias pessoas.
5. Quando o primeiro lead de teste chegar, o dono e os administradores recebem o aviso Lead aguardando mapeamento. Abra a aba Vincular campos. A coluna Campo recebido mostra os campos do último envio, com um valor de exemplo. Se o CRM reconhecer os nomes, aparece Preenchemos para você com sugestões. Em cada linha, escolha na coluna Destino no CRM para onde vai o campo, ou deixe em Não vincular (há também Ignorar este campo). Vincule pelo menos o Nome completo e o Telefone principal ou o E-mail: sem nenhum dos três, os leads ficam como Ignorado. Use Pré-visualizar para ver o contato e o lead que vão ser criados e clique em Salvar.
6. Os leads guardados entram na hora, e a mensagem diz quantos: “Mapeamento salvo. 3 leads guardados entraram para processamento.” Sem lead guardado, a mensagem é “Mapeamento salvo com sucesso”. Se ainda sobrar algum, use Reprocessar N aguardando na aba Eventos recebidos.
7. Acompanhe na aba Eventos recebidos. Em Detalhes, cada envio mostra o JSON recebido e o que aconteceu com ele.
8. Se o token vazar ou a equipe do site mudar, clique em Girar token (gerar um token novo) na aba Endereço e token e confirme. O antigo para de funcionar na hora, sem transição: combine o momento com a equipe do site, porque os envios feitos entre a troca no CRM e a troca no site são recusados. O endereço continua o mesmo; entregue só o token novo.
9. Para desligar uma conexão, use o ícone de lixeira na lista de conexões. O endereço para de responder na hora, e os leads que já entraram continuam no CRM.

Quando algo dá errado

• Falhou: abra Detalhes para ver o motivo, como um valor fora do formato. Corrija o vínculo ou peça à equipe do site para corrigir o envio, e clique em Reprocessar.
• Ignorado: o envio veio sem nome, e-mail e telefone. Confira se esses campos estão vinculados. Os envios que já ficaram como Ignorado não voltam; os próximos entram.
• O dono e os administradores recebem os avisos Lead aguardando mapeamento e Falha ao processar lead.

O que cada selo quer dizer

Onde aparece	Selo	O que significa
Cartão Genérico	Nenhuma conexão	Ainda não existe conexão.
Cartão e lista de conexões	Falta vincular	A conexão ainda não tem campos vinculados. Aparece logo depois de criar, antes do primeiro lead. Os leads que chegarem ficam guardados.
Página da conexão	Nenhum lead ainda	O site ainda não enviou nada.
Lista e página da conexão	N guardados	Leads que chegaram e esperam você salvar o vínculo.
Cartão Genérico	Aguardando 1º lead	Os campos estão vinculados, mas nenhum lead chegou ainda.
Cartão Genérico	Recebendo	Tudo certo.
Cartão Genérico	N sem lead	Uma conexão recebia leads e está há mais de 14 dias sem receber. Fale com a equipe do site.