# Configurar webhooks

Cadastre um destino global para os eventos de cada servidor. As instâncias podem herdar esse destino, usar uma configuração própria ou manter a entrega desativada.

## Cadastro pelo console

No [console central](https://wpp.atendro.cloud), abra **Servidores → servidor → Configurações de webhook**. Informe a URL HTTPS do novo receptor AtendroZAP no Atendro, o segredo de assinatura e os eventos desejados.

O global pertence ao servidor selecionado. As instâncias atuais sem exceção e as novas instâncias herdam URL, segredo e eventos. A configuração é persistida e permanece após o reinício.

## Cadastro pela API

Use [POST /v1/webhook](https://wpp.atendro.cloud/docs/api/configure-global-webhook.md) na URL da API do servidor e o header `admintoken`.

```json
{
  "action": "update",
  "url": "https://seu-atendro.example/webhooks/atendrozap",
  "secret": "<SEGREDO_PRIVADO_DO_WEBHOOK>",
  "events": ["connection", "messages", "messages_update", "messages_edit", "groups"],
  "enabled": true
}
```

Substitua os marcadores no backend privado. A URL precisa ser HTTPS pública, sem credenciais embutidas ou redirecionamento. O segredo aceita até 256 caracteres ASCII sem espaços e não é devolvido nas consultas.

## Herança por instância

| Ação | Endpoint ou opção | Efeito |
|---|---|---|
| Usar o global | `POST /webhook`, `action: inherit` | A instância acompanha o destino do servidor |
| Criar exceção | `POST /webhook`, `action: update` | URL e eventos próprios para essa instância |
| Desativar na instância | `POST /webhook`, `action: delete` | Impede que futuras alterações globais reativem a entrega |
| Pausar o global | `POST /v1/webhook`, `enabled: false` | Pausa somente as instâncias que herdam |
| Remover o global | `POST /v1/webhook`, `action: delete` | Remove inscrições herdadas e preserva exceções |

Cadastros anteriores à migração de herança permanecem como configurações próprias. Escolha **Usar webhook global** em cada instância que deve passar a herdar.

## Eventos entregues

| Evento | Uso no Atendro |
|---|---|
| `connection` | Atualizar o estado da instância |
| `messages` | Receber mensagens novas e ações projetadas nesse formato |
| `messages_update` | Atualizar entrega, leitura e exclusão |
| `messages_edit` | Atualizar o conteúdo de uma mensagem existente |
| `groups` | Atualizar informações e participantes de grupos |
| `call` | Acompanhar estados das ligações em instâncias `calls` |
| `limits` | Informar limites da sessão |
| `undecryptable` | Tratar mensagem que não pôde ser decifrada |

`qrcode`, `chats` e `history` não são entregues. Nomes de compatibilidade aceitos aparecem em `ignoredEvents`; nomes desconhecidos retornam `400 invalid_event`. `addUrlEvents` e `addUrlTypesMessages` devem ser `false`.

## Mudança de URL e backlog

A mesma URL preserva cursor e saúde de entrega. Um segredo omitido preserva o anterior quando a URL é a mesma. Ao mudar de URL, informe o segredo do novo destino; a inscrição começa após os eventos já existentes.

Registrar um webhook não reenvia automaticamente o histórico. Eventos anteriores ao registro não são entregues por essa inscrição.

## Acompanhar a entrega

[GET /webhook](https://wpp.atendro.cloud/docs/api/get-webhook.md) informa `inheritedGlobal` e `deliveryStatus`, incluindo pendentes, dead-letters e a última falha. [GET /webhook/errors](https://wpp.atendro.cloud/docs/api/get-webhook-errors.md) consulta as falhas recentes sem devolver payloads.

O receptor deve validar a assinatura, deduplicar eventos e responder 2xx somente após uma gravação durável. Continue em [implementar o receptor](https://wpp.atendro.cloud/docs/guias/receber-eventos.md) e [payloads e política de entrega](https://wpp.atendro.cloud/docs/guias/eventos.md).