Mudança de Etapa

Visão Geral

O webhook de Mudança de Etapa é disparado pela Morada.ai sempre que um deal avança ou retrocede no funil de vendas. O payload inclui dados completos do deal, contato, produto, origem e um resumo da conversa gerado por IA.

Se a opção shouldSendOnlyOnDealTransfer estiver ativada, o webhook será enviado apenas quando o deal for transferido para atendimento humano — ignorando mudanças intermediárias de etapa.

Payload

{
  "deal": {
    "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "status": "active",
    "stageCode": "deal_transferred",
    "name": "João Silva - Apt 302 Torre A",
    "conversationId": "f1e2d3c4-5678-90ab-cdef-1234567890ab",
    "partnerId": "b2c3d4e5-6789-01ab-cdef-2345678901bc"
  },
  "person": {
    "id": "c3d4e5f6-7890-12ab-cdef-3456789012cd",
    "name": "João Silva",
    "email": "joao.silva@email.com",
    "phone": "5511999999999"
  },
  "product": {
    "id": "d4e5f6a7-8901-23ab-cdef-4567890123de",
    "name": "Edifício Aurora - Torre A"
  },
  "source": {
    "id": "e5f6a7b8-9012-34ab-cdef-5678901234ef",
    "code": "whatsapp",
    "name": "WhatsApp - Site"
  },
  "conversationReport": "O lead demonstrou interesse no apartamento de 2 quartos com suíte. Informou renda familiar de R$ 15.000 e tem aprovação de crédito prévia. Solicitou agendamento de visita para o final de semana.",
  "appointmentDate": "17-05-2026 14:30",
  "metadata": {
    "timestamp": "2026-05-13T18:30:00.000Z",
    "eventType": "deal_stage_change",
    "stageId": "f6a7b8c9-0123-45ab-cdef-6789012345f0"
  }
}

Campos

deal

Campo	Tipo	Descrição
`deal.id`	string	ID único do deal
`deal.status`	string	Status atual: `active`, `won`, `lost`
`deal.stageCode`	string	Código da etapa atual no funil
`deal.name`	string	Nome do deal
`deal.conversationId`	string \| null	ID da conversa associada
`deal.partnerId`	string	ID do parceiro

person

Campo	Tipo	Descrição
`person.id`	string	ID único do contato
`person.name`	string \| null	Nome completo
`person.email`	string \| null	E-mail
`person.phone`	string \| null	Telefone com DDI (ex: `5511999999999`)

product

O campo product só é enviado quando o deal possui um produto/empreendimento associado.

Campo	Tipo	Descrição
`product.id`	string	ID do produto/empreendimento
`product.name`	string	Nome do produto/empreendimento

source

Campo	Tipo	Descrição
`source.id`	string	ID da origem
`source.code`	string	Código da origem (ex: `whatsapp`, `instagram`, `web`)
`source.name`	string	Nome descritivo da origem

Outros campos

Campo	Tipo	Descrição
`conversationReport`	string \| null	Resumo da conversa gerado por IA — contém os principais pontos discutidos, dados coletados e intenções identificadas
`appointmentDate`	string \| null	Data do agendamento associado, se houver. Formato: `dd-MM-yyyy HH:mm` (horário de Brasília)
`metadata.timestamp`	string	Data/hora do envio do webhook (ISO 8601)
`metadata.eventType`	string	Sempre `"deal_stage_change"`
`metadata.stageId`	string	ID da nova etapa no funil

Exemplo de uso

app.post("/webhook/morada", (req, res) => {
  const { deal, person, conversationReport, metadata } = req.body;

  console.log(`Deal ${deal.id} movido para etapa ${deal.stageCode}`);
  console.log(`Contato: ${person.name} (${person.phone})`);

  if (conversationReport) {
    // Salvar resumo da conversa no seu CRM
    console.log(`Resumo IA: ${conversationReport}`);
  }

  res.status(200).json({ received: true });
});

@app.route("/webhook/morada", methods=["POST"])
def handle_webhook():
    data = request.json

    deal = data["deal"]
    person = data["person"]
    report = data.get("conversationReport")

    print(f"Deal {deal['id']} movido para {deal['stageCode']}")
    print(f"Contato: {person['name']} ({person['phone']})")

    if report:
        print(f"Resumo IA: {report}")

    return jsonify({"received": True}), 200

Resposta esperada

Retorne um status HTTP 200 para confirmar o recebimento:

{
  "received": true
}

Se o seu endpoint retornar um status diferente de 2xx ou não responder dentro do timeout, a Morada.ai poderá tentar reenviar o evento. Implemente idempotência para lidar com entregas duplicadas.

Visão Geral

Deals

Leads

Notificações

Produtos

Data

Webhooks

Visão Geral

Payload

Campos

deal

person

product

source

Outros campos

Exemplo de uso

Resposta esperada

​Visão Geral

​Payload

​Campos

​deal

​person

​product

​source

​Outros campos

​Exemplo de uso

​Resposta esperada

Visão Geral

Payload

Campos

deal

person

product

source

Outros campos

Exemplo de uso

Resposta esperada