Eventos Genéricos

Visão Geral

Os Eventos Genéricos são webhooks disparados pela Morada.ai para eventos que não possuem um payload especializado. Eles seguem uma estrutura padronizada com os dados brutos do evento e um contexto opcional com informações do deal, contato e produto.

Eventos suportados

Evento	Descrição
`Deal.created`	Novo deal criado
`Deal.owner-assigned`	Responsável atribuído ao deal
`DealLog.created`	Log registrado no deal
`Conversation.created`	Nova conversa iniciada
`Conversation.closed`	Conversa encerrada
`Conversation.updated`	Conversa atualizada
`ConversationFunction.completed`	Função executada durante conversa (ex: busca de imóveis, simulação)
`DeskTicket.created`	Ticket de atendimento criado
`DeskTicket.owner-assigned`	Responsável atribuído ao ticket
`Person.updated`	Dados do contato atualizados

Payload

{
  "event": {
    "type": "Conversation.closed",
    "entity": "Conversation",
    "action": "closed",
    "timestamp": "2026-05-13T18:30:00.000Z",
    "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab"
  },
  "data": {
    "id": "f1e2d3c4-5678-90ab-cdef-1234567890ab",
    "dealId": "b2c3d4e5-6789-01ab-cdef-2345678901bc",
    "channel": "whatsapp",
    "status": "closed",
    "closedAt": "2026-05-13T18:30:00.000Z"
  },
  "context": {
    "person": {
      "id": "c3d4e5f6-7890-12ab-cdef-3456789012cd",
      "name": "Ana Lima",
      "email": "ana@email.com",
      "phone": "5511966666666"
    },
    "deal": {
      "id": "b2c3d4e5-6789-01ab-cdef-2345678901bc",
      "status": "active",
      "stageCode": "new_lead"
    },
    "product": {
      "id": "d4e5f6a7-8901-23ab-cdef-4567890123de",
      "name": "Loteamento Solar"
    },
    "source": {
      "id": "e5f6a7b8-9012-34ab-cdef-5678901234ef",
      "code": "whatsapp",
      "name": "WhatsApp Orgânico"
    }
  }
}

Campos

event

Campo	Tipo	Descrição
`event.type`	string	Tipo completo do evento no formato `Entidade.ação` (ex: `Conversation.closed`)
`event.entity`	string	Entidade do evento: `Deal`, `Conversation`, `DeskTicket`, `ConversationFunction`, `DealLog`, `Person`
`event.action`	string	Ação do evento: `created`, `updated`, `closed`, `completed`, `owner-assigned`
`event.timestamp`	string	Data/hora do evento (ISO 8601)
`event.id`	string	ID único do evento

data

O campo data contém os dados brutos do evento. A estrutura varia conforme a entidade — os exemplos abaixo ilustram os campos mais comuns:

Deal.created

{
  "id": "uuid",
  "personId": "uuid",
  "partnerId": "uuid",
  "status": "active",
  "stageCode": "new_lead"
}

Conversation.closed

{
  "id": "uuid",
  "dealId": "uuid",
  "channel": "whatsapp",
  "status": "closed",
  "closedAt": "2026-05-13T18:30:00.000Z"
}

DeskTicket.created

{
  "id": "uuid",
  "dealId": "uuid",
  "conversationId": "uuid",
  "status": "open",
  "priority": "normal"
}

ConversationFunction.completed

{
  "id": "uuid",
  "dealId": "uuid",
  "functionName": "searchProperties",
  "result": { "..." : "..." }
}

Person.updated

{
  "id": "uuid",
  "name": "Ana Lima",
  "email": "ana@email.com",
  "phone": "5511966666666"
}

context

O campo context é opcional e preenchido com base no dealId do evento. Se o evento não estiver vinculado a um deal, o contexto pode ser parcial ou ausente.

Campo	Tipo	Descrição
`context.person.id`	string	ID do contato
`context.person.name`	string \| null	Nome completo
`context.person.email`	string \| null	E-mail
`context.person.phone`	string \| null	Telefone com DDI
`context.deal.id`	string	ID do deal
`context.deal.status`	string \| null	Status: `active`, `won`, `lost`
`context.deal.stageCode`	string \| null	Código da etapa no funil
`context.product.id`	string	ID do produto/empreendimento
`context.product.name`	string \| null	Nome do produto/empreendimento
`context.source.id`	string	ID da origem
`context.source.code`	string	Código da origem
`context.source.name`	string	Nome da origem

Exemplo de uso

app.post("/webhook/morada", (req, res) => {
  const { event, data, context } = req.body;

  console.log(`Evento: ${event.type} (${event.id})`);

  switch (event.type) {
    case "Conversation.closed":
      console.log(`Conversa encerrada para deal ${data.dealId}`);
      if (context?.person) {
        console.log(`Contato: ${context.person.name}`);
      }
      break;

    case "Deal.created":
      console.log(`Novo deal criado: ${data.id}`);
      break;

    case "DeskTicket.created":
      console.log(`Ticket aberto: ${data.id}`);
      break;

    default:
      console.log(`Evento não tratado: ${event.type}`);
  }

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

@app.route("/webhook/morada", methods=["POST"])
def handle_webhook():
    data = request.json
    event = data["event"]
    event_data = data["data"]
    context = data.get("context", {})

    print(f"Evento: {event['type']} ({event['id']})")

    if event["type"] == "Conversation.closed":
        person = context.get("person", {})
        print(f"Conversa encerrada - Contato: {person.get('name')}")

    elif event["type"] == "Deal.created":
        print(f"Novo deal: {event_data['id']}")

    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

Eventos Genéricos

Visão Geral

Eventos suportados

Payload

Campos

event

data

context

Exemplo de uso

Resposta esperada

​Visão Geral

​Eventos suportados

​Payload

​Campos

​event

​data

​context

​Exemplo de uso

​Resposta esperada

Visão Geral

Eventos suportados

Payload

Campos

event

data

context

Exemplo de uso

Resposta esperada