> ## Documentation Index
> Fetch the complete documentation index at: https://docs.morada.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Receba notificações em tempo real sobre eventos da Morada.ai no seu sistema.

## 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

<Steps>
  <Step title="Evento ocorre">
    Algo acontece na plataforma — um lead envia uma mensagem, um deal muda de etapa, um agendamento é criado.
  </Step>

  <Step title="Payload é montado">
    A Morada.ai monta um JSON com os dados do evento, incluindo contexto do deal, contato e produto.
  </Step>

  <Step title="POST é enviado">
    Um `POST` HTTP é enviado para a URL configurada pelo parceiro, com o payload no body.
  </Step>

  <Step title="Confirmação">
    Seu sistema processa os dados e retorna um status HTTP `2xx` para confirmar o recebimento.
  </Step>
</Steps>

## Configuração

A configuração de webhooks é feita pela equipe da Morada diretamente na plataforma. Para cada webhook, você informa:

| Parâmetro | Obrigatório | Descrição                                            |
| --------- | :---------: | ---------------------------------------------------- |
| `url`     |     Sim     | URL do seu endpoint que receberá os eventos          |
| `headers` |     Não     | Headers customizados (ex: API key para autenticação) |
| `eventos` |     Sim     | Quais eventos deseja receber                         |

<Info>
  Entre em contato com o suporte da Morada para configurar seus webhooks: [support.morada.ai](https://support.morada.ai)
</Info>

## Eventos disponíveis

| Evento                   | Descrição                                     |                       Documentação                       |
| ------------------------ | --------------------------------------------- | :------------------------------------------------------: |
| Mudança de Etapa         | Deal avança ou retrocede no funil             |   [Ver payload](/api-reference/webhooks/mudanca-etapa)   |
| Agendamento              | Visita ou reunião criada/atualizada           |    [Ver payload](/api-reference/webhooks/agendamento)    |
| Nova Mensagem            | Mensagem enviada ou recebida na conversa      |   [Ver payload](/api-reference/webhooks/nova-mensagem)   |
| Enriquecimento de Imóvel | Dados do imóvel enriquecidos automaticamente  |   [Ver payload](/api-reference/webhooks/enriquecimento)  |
| Eventos Genéricos        | Deal criado, conversa encerrada, ticket, etc. | [Ver payload](/api-reference/webhooks/eventos-genericos) |

## Requisitos do seu endpoint

<Steps>
  <Step title="Método POST">
    Seu endpoint deve aceitar requisições `POST` com body JSON.
  </Step>

  <Step title="Resposta 2xx">
    Retorne qualquer status HTTP `2xx` para confirmar o recebimento.
  </Step>

  <Step title="Timeout de 30 segundos">
    O endpoint deve responder em até 30 segundos. Para processamentos demorados, aceite o webhook e processe de forma assíncrona.
  </Step>
</Steps>

## Boas práticas

<AccordionGroup>
  <Accordion title="Responda rápido, processe depois">
    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.
  </Accordion>

  <Accordion title="Implemente idempotência">
    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.
  </Accordion>

  <Accordion title="Proteja seu endpoint">
    Configure headers customizados (como uma API key) na configuração do webhook para validar que as requisições vêm da Morada.ai.
  </Accordion>

  <Accordion title="Monitore falhas">
    Registre logs de todos os webhooks recebidos. Se seu endpoint retornar erros, verifique os logs e corrija antes que eventos sejam perdidos.
  </Accordion>
</AccordionGroup>

<Warning>
  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.
</Warning>