Configurar webhooks
Destino global por servidor, herança, exceções e eventos disponíveis.
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, 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 na URL da API do servidor e o header admintoken.
{
"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 informa inheritedGlobal e deliveryStatus, incluindo pendentes, dead-letters e a última falha. GET /webhook/errors 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 e payloads e política de entrega.