Configurar webhooks de WhatsApp API: challenge y firma

Un webhook de producción tiene dos responsabilidades diferentes: superar el handshake de verificación cuando Meta registra el callback y procesar posteriormente las notificaciones POST de mensajes/estados. El verify token no sustituye la validación criptográfica de los POST.

1. Endpoint HTTPS

Publica una URL estable, por ejemplo https://api.tudominio.com/meta/whatsapp/webhook. No coloques CAPTCHA, login interactivo ni una redirección delante de esa ruta.

2. Verificación GET

Meta envía parámetros como hub.mode, hub.verify_token y hub.challenge. Compara el token recibido con el valor que configuraste. Si coincide y el modo es el esperado, devuelve el challenge como texto con HTTP 200.

GET /meta/whatsapp/webhook?hub.mode=subscribe&hub.verify_token=MI_TOKEN&hub.challenge=12345

if hub.mode == "subscribe" and hub.verify_token == ENV_VERIFY_TOKEN:
    return 200, hub.challenge
return 403

3. Suscribir la app a la WABA

POST https://graph.facebook.com/{VERSION}/{WABA_ID}/subscribed_apps
Authorization: Bearer {ACCESS_TOKEN}

Según la colección oficial de Meta, una respuesta exitosa contiene {"success":"true"}. Además debes tener configurado el producto Webhooks en la aplicación y la suscripción correspondiente al objeto/campo de WhatsApp.

4. Validar X-Hub-Signature-256

Los payloads se firman con SHA-256 y el App Secret. Calcula HMAC sobre el cuerpo crudo recibido y compara de forma segura contra el valor del header después del prefijo sha256=. Si tu framework parsea/re-serializa JSON antes del HMAC, la firma puede no coincidir.

expected = HMAC_SHA256(APP_SECRET, raw_request_body)
received = request.headers["X-Hub-Signature-256"].remove_prefix("sha256=")
if not constant_time_compare(expected, received):
    return 401

5. Responde rápido y procesa después

Valida, guarda/encola y responde. No llames a IA, ERP o servicios lentos antes del HTTP 200. Usa una clave idempotente porque un evento puede repetirse. Mantén una dead-letter queue para fallos que exceden los reintentos.

6. Datos que conviene registrar

WABA ID y Phone Number ID.
Message ID / wamid cuando exista.
Tipo de evento y timestamp.
Hash/clave de idempotencia.
Estado de procesamiento, latencia y código de error.
Evita duplicar indefinidamente el contenido completo de conversaciones en logs técnicos.

¿Tu empresa no necesita desarrollar esto?

Optimify ya integra la capa empresarial sobre WhatsApp API

Esta sección existe para equipos que realmente quieren construir o integrar. Si la empresa solo necesita CRM, multiagente, campañas, automatización e IA, MensajAPI recomienda comparar el costo de desarrollo y mantenimiento frente a usar Optimify, que ofrece una plataforma lista y soporte en español.

Ver alternativa gestionada con Optimify

Documentación oficial para mantener la integración actualizada

Versionado: los ejemplos usan {VERSION} en lugar de fijar una versión de Graph API. Sustituye esa variable por una versión vigente y soportada en tu aplicación y revisa cambios antes de actualizar producción.

Webhooks de WhatsApp API: configuración exacta para producción