Skip to main content

​
O que são Webhooks?

Webhooks permitem que a Morada.ai envie notificações automáticas para o seu sistema sempre que eventos relevantes acontecem — como uma nova mensagem recebida, uma mudança de etapa no funil, um agendamento criado ou uma conversa encerrada. Em vez de consultar a API repetidamente para verificar atualizações (polling), seu sistema recebe um POST HTTP em tempo real no endpoint que você configurar.

​
Como funciona

1

Evento ocorre

Algo acontece na plataforma — um lead envia uma mensagem, um deal muda de etapa, um agendamento é criado.
2

Payload é montado

A Morada.ai monta um JSON com os dados do evento, incluindo contexto do deal, contato e produto.
3

POST é enviado

Um POST HTTP é enviado para a URL configurada pelo parceiro, com o payload no body.
4

Confirmação

Seu sistema processa os dados e retorna um status HTTP 2xx para confirmar o recebimento.

​
Configuração

A configuração de webhooks é feita pela equipe da Morada diretamente na plataforma. Para cada webhook, você informa:
ParâmetroObrigatórioDescrição
urlSimURL do seu endpoint que receberá os eventos
headersNãoHeaders customizados (ex: API key para autenticação)
eventosSimQuais eventos deseja receber
Entre em contato com o suporte da Morada para configurar seus webhooks: support.morada.ai

​
Eventos disponíveis

EventoDescriçãoDocumentação
Mudança de EtapaDeal avança ou retrocede no funilVer payload
AgendamentoVisita ou reunião criada/atualizadaVer payload
Nova MensagemMensagem enviada ou recebida na conversaVer payload
Enriquecimento de ImóvelDados do imóvel enriquecidos automaticamenteVer payload
Eventos GenéricosDeal criado, conversa encerrada, ticket, etc.Ver payload

​
Requisitos do seu endpoint

1

Método POST

Seu endpoint deve aceitar requisições POST com body JSON.
2

Resposta 2xx

Retorne qualquer status HTTP 2xx para confirmar o recebimento.
3

Timeout de 30 segundos

O endpoint deve responder em até 30 segundos. Para processamentos demorados, aceite o webhook e processe de forma assíncrona.

​
Boas práticas

Retorne 200 assim que receber o webhook e coloque o processamento em uma fila. Isso evita timeouts e garante que você não perca eventos.
Use o campo metadata.timestamp ou IDs dos objetos para evitar processar o mesmo evento duas vezes. Embora raro, um mesmo evento pode ser entregue mais de uma vez.
Configure headers customizados (como uma API key) na configuração do webhook para validar que as requisições vêm da Morada.ai.
Registre logs de todos os webhooks recebidos. Se seu endpoint retornar erros, verifique os logs e corrija antes que eventos sejam perdidos.
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. Recomendamos que seu sistema seja idempotente para lidar com entregas duplicadas.