Verificar un endpoint de webhook de WhatsApp
Antes de entregar cualquier evento, Meta llama a tu endpoint con un GET que lleva hub.mode, hub.verify_token y hub.challenge. Tu endpoint debe comparar el token y devolver el challenge como cuerpo crudo de la respuesta. Cualquier otra cosa y la entrega nunca empieza.
El valor que debe devolverse como cuerpo de la respuesta.
El valor de hub.mode en una petición de verificación.
El único esquema que Meta verifica. HTTP se rechaza antes de la llamada.
¿Qué envía exactamente Meta?
Una petición GET a tu URL con tres parámetros de query. hub.mode viene con el valor subscribe. hub.verify_token es el token que configuraste al definir el destino. hub.challenge es un valor que Meta genera para ese intento.
Tu endpoint debe comparar hub.verify_token con el token que elegiste y, si coincide, responder 200 con hub.challenge como todo el cuerpo de la respuesta. Sin envolverlo en JSON, sin comillas alrededor, sin el salto de línea final que algunos frameworks agregan por defecto.
Si el token no coincide, responde 403. Ese es el protocolo entero, y es pequeño a propósito.
¿Por qué una respuesta equivocada falla en silencio?
Porque que la verificación falle no es un error en tu sistema, es una ausencia en el de Meta.
Cuando el challenge no se devuelve correctamente, Meta simplemente no empieza a entregar en ese destino. Tu servidor devuelve 200 a la verificación, tus logs muestran que llegó una petición, y ningún panel en ninguna parte reporta un problema. El único síntoma es que los mensajes nunca llegan, lo que la mayoría diagnostica como un problema de Coexistencia en lugar de un problema de handshake.
Por eso vale la pena validar antes de la llamada. Comprobamos que la URL sea HTTPS y que se haya indicado un verify token antes de hacer la petición al Graph, así un destino malformado falla de inmediato en vez de parecer conectado.
¿Qué más puede bloquear la verificación?
Tres cosas que no tienen nada que ver con el código.
Autenticación delante del endpoint. Un gateway, una capa de basic auth o una lista de IP permitidas van a rechazar la petición de Meta, y Meta no tiene ninguna credencial que presentar. La ruta de verificación tiene que ser accesible sin eso.
Una redirección. Meta llama a la URL que le diste, y un 301 hacia un host canónico no se sigue de un modo que complete el handshake. Entrégale la URL final.
Y un framework que serializa la respuesta. Devolver una cadena desde un handler que envuelve todo en JSON produce un cuerpo con comillas alrededor del challenge, y eso no coincide.
Errores comunes
- Devolver JSON. El cuerpo tiene que ser el valor crudo del challenge, sin nada alrededor.
- Poner el endpoint detrás de autenticación. Meta no tiene credenciales y va a ser rechazada.
- Darle a Meta una URL que redirige. Usa la final.
EasyCoexistence valida que un destino sea HTTPS y tenga verify token antes de llamar a Meta, y registra un handshake fallido en la línea de tiempo de la conexión en vez de descartar el destino.
Preguntas frecuentes
¿Qué token debo usar?
Cualquier cadena que elijas. Existe para que tu endpoint distinga la petición de Meta de la de cualquiera que descubra la URL.
¿Con qué frecuencia ocurre la verificación?
En la configuración, y de nuevo cada vez que se define el destino. Un endpoint que funciona no se reverifica en cada evento.
¿Puedo probarlo yo mismo?
Sí. Llama a tu propio endpoint con los tres parámetros y comprueba que el cuerpo vuelve exactamente como el valor del challenge.
¿Y si mi servidor estaba caído durante la verificación?
El handshake falla y el destino no se activa. Guardarlo otra vez vuelve a ejecutarlo.
Sigue leyendo
¿Listo para empezar?
Configura WhatsApp Coexistence en minutos, no en meses. La app sigue funcionando en el teléfono.
Empezar prueba gratisVerificado el