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

# Webhooks

> Endpoints para recebimento de eventos de sistemas externos

## Webhooks

Base path: `/v1/webhooks`

Os webhooks são endpoints que recebem eventos de sistemas externos (WhatsApp, Stripe, etc.) e os processam internamente.

<Note>
  Os endpoints abaixo representam a estrutura planejada. A implementação detalhada será gerada durante o desenvolvimento.
</Note>

## WhatsApp

| Método | Endpoint                | Descrição                                |
| ------ | ----------------------- | ---------------------------------------- |
| `POST` | `/v1/webhooks/whatsapp` | Receber eventos do WhatsApp Business API |
| `GET`  | `/v1/webhooks/whatsapp` | Verificação do webhook (challenge)       |

### Eventos Processados

| Evento              | Ação no Sistema                                   |
| ------------------- | ------------------------------------------------- |
| `message.received`  | Registra mensagem no histórico, aciona triagem IA |
| `message.delivered` | Atualiza status de entrega da mensagem            |
| `message.read`      | Atualiza status de leitura da mensagem            |
| `message.failed`    | Registra falha de entrega                         |

## Stripe

| Método | Endpoint              | Descrição                 |
| ------ | --------------------- | ------------------------- |
| `POST` | `/v1/webhooks/stripe` | Receber eventos do Stripe |

### Eventos Processados

| Evento                          | Ação no Sistema                             |
| ------------------------------- | ------------------------------------------- |
| `invoice.paid`                  | Confirma pagamento, ativa/renova assinatura |
| `invoice.payment_failed`        | Registra falha, notifica administrador      |
| `customer.subscription.deleted` | Desativa conta do mandato                   |
| `customer.subscription.updated` | Atualiza plano do mandato                   |

<Warning>
  Os webhooks devem implementar validação de assinatura (signature verification) para garantir que os eventos recebidos são autênticos e não foram forjados.
</Warning>