¿Por qué Chatwoot responde 401 Unauthorized a los webhooks de WhatsApp?

En resumen: desde la versión 4.14, Chatwoot verifica el X-Hub-Signature-256 de las entregas de WhatsApp Cloud con el app_secret de la bandeja de entrada correspondiente. Un 401 significa una de dos cosas: ninguna bandeja de entrada coincide con el número, o su app_secret no es la clave que firmó la entrega. Las dos se corrigen en la bandeja de entrada, con la API de Chatwoot.

Las dos causas

• Ninguna bandeja de entrada coincide con el número. Chatwoot elige la bandeja por el número comercial y el Phone Number ID que vienen dentro del payload: el número de la bandeja debe ser tu número de WhatsApp en E.164 (+, código de país y número, sin espacios), y su phone_number_id debe ser el ID de ese número. Si nada coincide, Chatwoot verifica la firma solo con el WHATSAPP_APP_SECRET de la instalación. Ese valor está vacío en una instalación estándar, así que todas las entregas reciben 401.
• La clave es otra. El app_secret de la bandeja debe ser igual, byte por byte, a la clave que firmó la entrega. Un espacio al final cuenta. Después de generar una clave nueva, cada bandeja de entrada necesita la nueva.

WHATSAPP_APP_SECRET en el entorno no sirve. Chatwoot lee ese valor de la configuración de la instalación, que db:chatwoot_prepare crea vacía en una instalación estándar, así que el valor del entorno nunca se usa. Puedes quitar la variable.

Cómo corregirlo

1. Abre la entrega que falló en Registros de ZapClaw: ahí ves el estado y la respuesta sin procesar que devolvió Chatwoot. Un 401 con Cuerpo de la respuesta vacío viene de esta verificación de firma.

2. Corrige la bandeja de entrada con la API de Chatwoot. Un número que todavía no tiene bandeja la obtiene con el comando que el panel de ZapClaw muestra para él. En una bandeja que ya existe, envía todo el provider_config, con app_secret y source: manual_setup_v2: Chatwoot reemplaza el objeto en lugar de fusionarlo, y uno parcial se rechaza con Provider config Invalid Credentials. Si el número también está mal, agrega phone_number a channel en la misma llamada.

   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>"
         }
       }
     }'

   El app_secret es la Clave de firma de la sección de Chatwoot en ZapClaw. El ID de la bandeja de entrada es el número después de /settings/inboxes/ cuando abres su configuración. La consola de Rails también funciona: mira la guía (en inglés).

3. Haz clic en Enviar evento de prueba en la sección de Chatwoot de ZapClaw. Si sale bien, Chatwoot encontró la bandeja de entrada y aceptó la firma. La prueba va a tu primer número conectado, así que ese número también necesita una bandeja. Luego reenvía desde Registros las entregas que fallaron.

Directo desde Meta, sin ZapClaw

• La verificación es la misma, y la clave es el App Secret de tu app de Meta, con el que Meta firma cada entrega. Una bandeja de entrada creada con el Embedded Signup de Chatwoot se verifica con el WHATSAPP_APP_SECRET guardado en el Super Admin de Chatwoot: después de restablecer el App Secret en Meta, actualízalo ahí, no en la bandeja. Cualquier otra bandeja solo se verifica si tiene un app_secret, que entonces debe ser el App Secret.
• Un 401 al guardar la URL de callback y el token de verificación en el panel de apps de Meta viene de otra verificación, la del token. La URL es la dirección de tu Chatwoot, luego /webhooks/whatsapp/ y el número de la bandeja con su +. El token es el Token de verificación del Webhook de la pestaña Configuración de la bandeja en Chatwoot.

Un 404, Invalid OAuth access token y las respuestas que nunca salen de Chatwoot tienen su propia solución en la solución de problemas de Chatwoot (en inglés).