Dispara uma vez a cada mudança de status da instância — o mesmo valor que GET /status devolve. É o único webhook de conexão: com ele você mostra a tela de QR code na hora certa, libera o canal quando o número entra e avisa quando ele cai, sem consultar a API em loop.
Status
Motivo da desconexão
O QR code não vem no webhook
O código muda a cada poucos segundos, então ele nunca é enviado: status: "qr" é o sinal para o seu sistema começar a buscar GET /qr-code (e renovar enquanto o status for qr). Você recebe um instance_status quando a instância passa a aguardar o QR, não um por código gerado. Quando o cliente lê o código, chegam connecting → connected.
Configuração
instance_status_url em PUT /webhooks (ou PUT /webhooks/instance_status com { "value": "https://..." }), PUT /account/webhooks para o workspace inteiro, ou o campo Ao mudar o status da instância no painel. No modo de URL única ele já chega em single_url. Para silenciar sem apagar a URL: ignore_instance_status_callback: true.
Recomendações
- Trate
logged_out e banned como alertas: avise quem opera o número (e-mail, Slack). Enquanto isso, os envios continuam entrando na fila, a menos que disable_enqueue_when_disconnected esteja ligado.
- Não reaja a
disconnected com POST /restart automático: a reconexão já está em curso e reiniciar só atrasa.
- Eventos podem chegar fora de ordem numa retentativa: use
momment para não deixar um disconnected antigo derrubar um canal que já voltou.
GET /status continua sendo a fonte de verdade para consultas pontuais; o webhook evita ficar consultando em loop.
instance_status substituiu os antigos webhooks connected e disconnected (e os campos connected_url / disconnected_url). O que eles traziam está aqui: phone ao conectar, disconnect_reason + reason ao cair. Quem tinha uma dessas URLs configurada foi migrado automaticamente para instance_status_url.
