Configurar webhooks
Destino global por servidor, herança, exceções e eventos disponíveis.
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, 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 na URL da API do servidor, com o header token da instância. A alternativa administrativa é POST /v1/instances/{id}/webhook, com o header admintoken e o ID da instância desejada. Exemplo para ligações:
{
"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. 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 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.