Por que o Chatwoot responde 401 Unauthorized aos webhooks do WhatsApp?

Em resumo: desde a versão 4.14, o Chatwoot confere o X-Hub-Signature-256 das entregas do WhatsApp Cloud com o app_secret da caixa de entrada correspondente. Um 401 quer dizer uma de duas coisas: nenhuma caixa de entrada bate com o número, ou o app_secret dela não é a chave que assinou a entrega. As duas se resolvem na caixa de entrada, pela API do Chatwoot.

As duas causas

• Nenhuma caixa de entrada bate com o número. O Chatwoot escolhe a caixa de entrada pelo número comercial e pelo Phone Number ID que vêm no payload: o telefone da caixa precisa ser o seu número de WhatsApp em E.164 (+, código do país e número, sem espaços), e o phone_number_id dela precisa ser o ID desse número. Sem correspondência, o Chatwoot confere a assinatura só com o WHATSAPP_APP_SECRET da instalação. Ele fica vazio numa instalação padrão, então toda entrega leva 401.
• A chave é outra. O app_secret da caixa de entrada precisa ser igual, byte a byte, à chave que assinou a entrega. Espaço no final conta. Depois de gerar uma chave nova, toda caixa de entrada precisa receber a nova.

WHATSAPP_APP_SECRET no ambiente não ajuda. O Chatwoot lê esse valor das configurações da instalação, que o db:chatwoot_prepare cria vazias numa instalação padrão, então o valor do ambiente nunca é usado. Pode remover a variável.

Como resolver

1. Abra a entrega que falhou nos Logs do ZapClaw: eles mostram o status e a resposta bruta que o Chatwoot devolveu. Um 401 com Corpo da resposta vazio vem dessa verificação de assinatura.

2. Corrija a caixa de entrada pela API do Chatwoot. Um número que ainda não tem caixa ganha uma com o comando que o painel do ZapClaw mostra para ele. Numa caixa que já existe, mande todo o provider_config, com app_secret e source: manual_setup_v2: o Chatwoot substitui o objeto em vez de mesclar, e um parcial é recusado com Provider config Invalid Credentials. Se o telefone também estiver errado, inclua phone_number em channel na mesma chamada.

   curl -X PATCH "https://chatwoot.your-domain.com/api/v1/accounts/<ACCOUNT_ID>/inboxes/<INBOX_ID>" \
     -H "api_access_token: <CHATWOOT_ACCESS_TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{
       "channel": {
         "provider_config": {
           "api_key": "zc_live_xxx",
           "phone_number_id": "<PHONE_NUMBER_ID>",
           "business_account_id": "<WABA_ID>",
           "source": "manual_setup_v2",
           "app_secret": "<CHATWOOT_SIGNING_SECRET>"
         }
       }
     }'

   O app_secret é a Chave de assinatura da seção Chatwoot no ZapClaw. O ID da caixa de entrada é o número depois de /settings/inboxes/ quando você abre as configurações dela. O console do Rails também serve: veja o guia (em inglês).

3. Clique em Enviar evento de teste na seção Chatwoot do ZapClaw. Se der certo, o Chatwoot achou a caixa de entrada e aceitou a assinatura. O teste vai para o seu primeiro número conectado, então esse número também precisa de uma caixa. Depois, reenvie pelos Logs as entregas que falharam.

Direto da Meta, sem o ZapClaw

• A verificação é a mesma, e a chave é o App Secret do seu app da Meta, com o qual a Meta assina toda entrega. Uma caixa de entrada criada pelo Embedded Signup do Chatwoot é conferida com o WHATSAPP_APP_SECRET salvo no Super Admin do Chatwoot: depois de redefinir o App Secret na Meta, atualize lá, não na caixa. Qualquer outra caixa só é conferida se tiver um app_secret, que então precisa ser o App Secret.
• Um 401 na hora de salvar a URL de callback e o token de verificação no painel de apps da Meta vem de outra verificação, a do token. A URL é o endereço do seu Chatwoot, depois /webhooks/whatsapp/ e o telefone da caixa de entrada com o +. O token é o Token de verificação Webhook da aba Configuração da caixa no Chatwoot.

Um 404, o Invalid OAuth access token e respostas que nunca saem do Chatwoot têm soluções próprias na solução de problemas do Chatwoot (em inglês).