Saída de Leads

Eventos de Troca de Status

O Imobilead envia um evento automaticamente para o seu endpoint sempre que o corretor altera o status de um lead dentro do pipeline. Com base neste guia, você deve criar o endpoint real que vai receber esses eventos na sua ferramenta.

Webhook de saída Gatilho: troca de status Método POST · application/json

Visão geral

No Imobilead, o administrador configura Saídas para que os leads sejam enviados automaticamente para outro lugar de sua preferência. Uma das fontes de disparo é a Troca de Status dentro do pipeline.

Regra: o lead é enviado para o seu endpoint toda vez que ele for movido para o status configurado (ex.: Proposta, Venda Ganha, Finalizado).

Cada Saída é vinculada a um status específico. Se você precisa reagir a vários status, o administrador cria uma Saída para cada status, e todas podem apontar para o mesmo endpoint, basta diferenciar pelo campo status do payload.

Lista de Saídas configuradas, cada card vinculado a um status do pipeline
Ex: Três Saídas do tipo "Troca de Status", cada uma para um status diferente (Finalizado, Venda Ganha, Proposta), todas com o toggle Online ativo.

Como a Saída é configurada

A configuração é feita pelo administrador na tela Configurar saída - Webhook:

Tela de configuração da saída Webhook no painel do Imobilead
Tela de configuração da Saída, onde o administrador define o status-gatilho e a URL de envio.
Campo Descrição
Título Nome de identificação da Saída (ex.: "Troca de Status").
Fonte da saída Define o gatilho. Para este fluxo, usa-se Status do Pipeline (ex.: Finalizado). O lead é enviado sempre que for movido para esse status.
URL de envio O endpoint que você (parceiro) vai fornecer. É para lá que o POST será disparado.
Enviar dados do corretor Quando ligado, o payload inclui o objeto user com os dados do corretor responsável. Quando desligado, o objeto user não é enviado.
Cabeçalhos da requisição Headers customizados opcionais (ex.: um token de autenticação Authorization).
Mapeamento de Campos Permite renomear/mapear até 10 campos do payload para o formato que a sua ferramenta espera.

Requisição HTTP

Item Valor
Método POST
Content-Type application/json
Corpo JSON com os dados do lead (ver abaixo).
Headers customizados Opcionais, conforme configurado pelo administrador (ex.: Authorization).

Seu endpoint deve aceitar POST com corpo JSON e responder rapidamente.

Payload enviado

Exemplo de corpo enviado no POST. Todos os dados abaixo são fictícios / anonimizados e servem apenas para ilustrar o formato:

{
    "id": "a1b2c3d4-0000-4a1b-8c2d-000000000001",
    "nome": "Fulano de Tal",
    "email": "",
    "produto": "EMPREENDIMENTO EXEMPLO",
    "telefone": "+5581999990000",
    "tag": null,
    "created_at": "2026-07-22T04:37:44.000Z",
    "nova_data": "2026-07-22T04:37:44.000Z",
    "data_reativacao": null,
    "leadTransferedAt": null,
    "leadId": "a1b2c3d4-0000-4a1b-8c2d-000000000001",
    "facebook_leadgen_id": "0000000000000000",
    "previousUsers": [59000],
    "pipelineStatusId": "42ce9246-0000-4f0d-8312-000000000002",
    "pipelineStatus": "Em Atendimento",
    "produto_id": 176164,
    "user": {
        "nome": "Corretor Exemplo da Silva",
        "email": "corretor.exemplo@email.com",
        "whatsapp": "81999990000"
    },
    "status": "Em Atendimento",
    "statusId": "42ce9246-0000-4f0d-8312-000000000002"
}

Segundo exemplo (lead com tag preenchida, sem origem Meta e sem e-mail):

{
    "id": "66ebe352-0000-4310-8c6f-000000000005",
    "nome": "Beltrano Souza",
    "email": null,
    "produto": "RESIDENCIAL MODELO",
    "telefone": "+5581988880000",
    "tag": "novo",
    "created_at": "2026-07-22T13:29:19.000Z",
    "nova_data": "2026-07-22T13:29:19.000Z",
    "data_reativacao": null,
    "leadTransferedAt": null,
    "leadId": "66ebe352-0000-4310-8c6f-000000000005",
    "facebook_leadgen_id": null,
    "previousUsers": [59330],
    "pipelineStatusId": "3e9fbd1b-0000-4944-b3af-000000000006",
    "pipelineStatus": "Visita Agendada",
    "produto_id": 175411,
    "user": {
        "nome": "Corretora Exemplo Pereira",
        "email": "corretora.exemplo@email.com",
        "whatsapp": "81988880000"
    },
    "status": "Visita Agendada",
    "statusId": "3e9fbd1b-0000-4944-b3af-000000000006"
}

Dicionário de campos

Campo Tipo Descrição
id string (UUID) Identificador único do lead. Igual ao leadId.
leadId string (UUID) Identificador único do lead (mesmo valor de id). Use como chave de deduplicação.
nome string Nome do lead/contato.
email string | null E-mail do lead. Pode vir vazio ("") ou null quando não informado.
produto string Nome do produto/empreendimento de interesse.
produto_id number Identificador numérico do produto/empreendimento.
telefone string Telefone do lead com DDI (ex.: +5581999990000).
tag string | null Etiqueta do lead (ex.: "novo"). Pode ser null.
created_at string (ISO 8601, UTC) Data/hora de criação do lead.
nova_data string (ISO 8601, UTC) Data/hora associada ao evento/atualização atual.
data_reativacao string | null Data/hora de reativação do lead, se houver. null caso contrário.
leadTransferedAt string | null Data/hora da última transferência do lead, se houver. null caso contrário.
facebook_leadgen_id string | null ID do lead no Facebook Lead Ads, quando a origem for Meta. null quando não vier do Meta.
previousUsers number[] IDs dos corretores que já foram responsáveis pelo lead anteriormente.
status string Nome do status atual do lead no pipeline. Use este campo para saber qual gatilho disparou o evento.
statusId string (UUID) Identificador único do status atual. Igual ao pipelineStatusId.
pipelineStatus string Nome do status atual (mesmo valor de status).
pipelineStatusId string (UUID) Identificador único do status (mesmo valor de statusId).
user object | ausente Dados do corretor responsável. Só é enviado quando "Enviar dados do corretor" está ligado.

Objeto user (dados do corretor)

Presente apenas quando a opção "Enviar dados do corretor" estiver ativa na configuração da Saída.

Campo Tipo Descrição
user.nome string Nome do corretor responsável.
user.email string E-mail do corretor.
user.whatsapp string WhatsApp do corretor (sem DDI, apenas DDD + número).
Importante: trate a ausência do objeto user graciosamente, o corretor pode desligar esse envio a qualquer momento.

Observações importantes

  • Fuso horário das datas: todos os timestamps vêm em UTC (ISO 8601 com sufixo Z). Se sua ferramenta trabalha em horário de Brasília (BRT, UTC-3), faça a conversão no seu lado.
  • Campos podem vir vazios ou nulos: email pode ser "" ou null; tag, data_reativacao, leadTransferedAt e facebook_leadgen_id podem ser null.
  • id e leadId são idênticos, assim como status/pipelineStatus e statusId/pipelineStatusId.
  • Deduplicação: um mesmo lead pode disparar vários eventos ao longo do tempo. Use leadId + status (ou nova_data) para identificar cada evento.
  • Novos campos: o payload pode ganhar novos campos no futuro. Implemente seu parser de forma tolerante (ignore campos desconhecidos em vez de rejeitar a requisição).

Resposta esperada do seu endpoint

O Imobilead considera o disparo bem-sucedido quando o seu endpoint responde com HTTP 2xx (ex.: 200 OK).

Código interno Significado
200 Disparo realizado com sucesso, seu endpoint recebeu e respondeu 2xx.
102 Status interno de preparação do envio (PREPARING_TO_SEND). É um log intermediário do Imobilead, não uma resposta do seu endpoint.
Tela de logs de envio da Saída, com status HTTP, mensagem e lead correspondente
Cada disparo fica registrado nos Logs da Saída, com o status HTTP retornado, a mensagem e o lead correspondente. É por aqui que o corretor acompanha se os eventos estão chegando na sua ferramenta.

Boas práticas para o endpoint

Responda rápido

Retorne 2xx e processe de forma assíncrona. Evite deixar a requisição aberta durante processamentos demorados.

Seja idempotente

Se receber o mesmo leadId + evento mais de uma vez, não duplique o registro.

Valide autenticação

Aplique validação via header customizado, caso configurado pelo corretor.

Sinalize falhas reais

Retorne 4xx/5xx apenas quando realmente falhar, isso ajuda o corretor a identificar problemas nos Logs da Saída.

Checklist para o parceiro

  • Criar endpoint público que aceite POST com corpo application/json.
  • Responder 2xx rapidamente ao receber o evento.
  • Fazer o parse dos campos conforme o dicionário.
  • Tratar o objeto user como opcional.
  • Converter as datas de UTC para o fuso desejado, se necessário.
  • Implementar deduplicação por leadId + evento.
  • (Opcional) Definir com o time Imobilead um header de autenticação.
  • Informar a URL de envio final para configuração da Saída.