Eventos de troca de status

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 no painel do Imobilead, cada card vinculado a um status do pipeline — Exemplo: três Saídas do tipo "Troca de Status", cada uma para um status diferente (Proposta, Visita agendada e Sem atendimento), 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 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 sem erro: 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.

Cada disparo fica registrado nos Logs da Saída, com o status HTTP retornado, a mensagem e o lead correspondente. É por lá 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 a 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 um 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.