# Configurar webhooks

Cada instância pode ter sua própria URL de webhook, segredo de assinatura e
seleção de eventos. Configurar uma instância não altera as demais. Isso vale
tanto para instâncias de mensagens (`whatsapp`) quanto de ligação (`calls`).

## Cadastro pelo console

No [console central](https://wpp.atendro.cloud), abra **Servidores → servidor
→ instância → Webhook**, ou use **Configurar** na coluna Webhook da listagem.
Informe a URL HTTPS do receptor, o segredo de assinatura e os eventos desejados.
Clique em **Salvar webhook desta instância**.

A configuração fica persistida após reinícios. Para ligações, selecione
`call`, `call_settings` e `connection`; para mensagens, selecione `messages`,
`messages_update`, `messages_edit` e `connection`, conforme a integração.

## Cadastro pela API

Use [POST /webhook](https://wpp.atendro.cloud/docs/api/configure-webhook.md) na URL da API do servidor,
com o header `token` da instância. A alternativa administrativa é
[POST /v1/instances/{id}/webhook](https://wpp.atendro.cloud/docs/api/admin-configure-webhook.md), com
o header `admintoken` e o ID da instância desejada. Exemplo para ligações:

```json
{
  "action": "update",
  "url": "https://seu-atendro.example/webhooks/atendrozap",
  "secret": "<SEGREDO_PRIVADO_DO_WEBHOOK>",
  "events": ["connection", "call", "call_settings"],
  "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.

Consulte `GET /webhook` com o mesmo token, ou `GET /v1/instances/{id}/webhook`
com `admintoken`, para conferir a configuração. `inheritedGlobal: false`
confirma um cadastro próprio. O segredo não é devolvido.

## Padrão global opcional

O destino global continua disponível por `GET/POST /v1/webhook` com
`admintoken`. Instâncias sem configuração própria podem herdá-lo; um
cadastro feito na instância substitui essa herança. Configurações próprias
são preservadas quando o global muda. Para desativar a entrega de uma
instância, use `action: delete`.

| 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` |
| `call_settings` | Sincronizar o limite por instância `calls` e sua versão após cada alteração aceita |
| `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`.

Instâncias `calls` não persistem nem publicam eventos de mensagens, recibos,
edições, grupos ou `undecryptable`; mantêm chamadas, configuração e ciclo de
vida (`connection` e `limits`). O filtro vale também para eventos de mensagens
antigos ainda na fila. A inscrição em `call` não inclui `call_settings`:
adicione esse nome preservando a URL, o segredo, os filtros e os demais eventos
da inscrição existente. Em uma configuração herdada, preserve a herança;
alterar o webhook global exige autorização administrativa.

O recurso é anunciado por `capabilities.calls_settings_webhook`. A integração
deve fazer a leitura inicial por `GET /instance/status` e acompanhar versões,
conforme o [guia de chamadas](https://wpp.atendro.cloud/docs/guias/chamadas-de-voz.md). Essas adições ainda
dependem de publicação no servidor utilizado.

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