Probar Webhooks de WhatsApp Localmente en 5 minutos

Prueba webhooks de WhatsApp en 5 minutos con un túnel seguro hacia tu servidor local

Desarrollar aplicaciones que se integren con la plataforma WhatsApp Business abre oportunidades únicas para conversar con usuarios en tiempo real. El corazón de esta integración son los webhooks, que envían notificaciones a tu servidor cuando llegan mensajes u ocurren eventos. El reto clásico para cualquier desarrollador es que WhatsApp exige una URL HTTPS pública, mientras que tu entorno de desarrollo está en localhost y no es accesible desde internet.

En esta guía aprenderás a exponer de forma segura tu servidor local para recibir webhooks de WhatsApp, acelerar tu ciclo de pruebas e iterar con rapidez. Usaremos un receptor de webhooks con Node.js y Express, y un túnel público con Tunnelmole.

Al finalizar serás capaz de entender el papel de los webhooks de WhatsApp, crear un manejador básico en Express, instalar y usar Tunnelmole para obtener una URL pública HTTPS, configurar tu App de Meta para enviar webhooks a tu entorno local, y probar y depurar tu integración en tiempo real.

Que son los webhooks de WhatsApp

Los webhooks son mensajes automáticos que WhatsApp envía a tu servidor cuando sucede un evento. En vez de consultar repetidamente a la API si hay novedades, WhatsApp te notifica de forma proactiva mediante una solicitud HTTP a una URL de devolución configurada por ti. Entre los eventos más comunes están mensajes nuevos, cambios de estado de mensajes enviados, actualizaciones de cuenta y clics en botones de mensajes interactivos.

Para usarlos, debes configurar una aplicación de WhatsApp Business en la consola de Meta for Developers. Durante el proceso te pedirán una URL de devolución y un token de verificación. La URL debe ser pública y segura con HTTPS, de ahí la necesidad de un túnel durante el desarrollo local.

Por que necesitas un túnel en desarrollo local

Tu servidor local escucha en direcciones como https://localhost:3000 o https://127.0.0.1:3000, accesibles solo desde tu equipo. WhatsApp, desde su infraestructura en internet, no puede alcanzar localhost directamente. Un servicio de túnel crea una conexión segura entre tu máquina y un servidor público, entregándote una URL accesible desde internet que reenvía el tráfico a tu servidor local.

Con un túnel puedes recibir webhooks reales, evitar mocks imprecisos, depurar en tiempo real con puntos de interrupción y acelerar el desarrollo sin desplegar a un entorno de staging.

Presentacion de Tunnelmole

Tunnelmole es una herramienta open source, rápida y sencilla que otorga una URL pública a tus servidores locales con un solo comando. Sus ventajas incluyen código abierto en GitHub, servicio alojado gratuito ideal para desarrollo, posibilidad de autoalojamiento para casos avanzados y dominios propios, e instalación simple al ser una aplicación nativa de NodeJS.

Guia paso a paso para probar webhooks de WhatsApp con Tunnelmole

Prerrequisitos Node.js 16.10 o superior con npm; acceso a la plataforma WhatsApp Business mediante la consola de Meta for Developers; un número personal de prueba para enviar mensajes al número de prueba de tu app.

Paso 1 Crear un receptor de webhooks con Express Crea una carpeta y un proyecto: mkdir whatsapp-webhook-test, cd whatsapp-webhook-test, npm init -y, npm install express body-parser. Luego implementa un servidor con Express que escuche en el puerto 3000 y exponga dos endpoints: GET en la ruta slash webhook para la verificación inicial que debe responder con el challenge cuando el token recibido coincida con tu token secreto VERIFY_TOKEN, y POST en la ruta slash webhook para recibir el payload de notificaciones. Registra el cuerpo recibido y devuelve 200 OK para confirmar la recepción. Usa un token secreto fuerte y guarda VERIFY_TOKEN como variable segura.

Paso 2 Instalar y ejecutar Tunnelmole Instala Tunnelmole con el comando: curl -O https://install.tunnelmole.com/xD345/install ampersandampersand sudo bash install. En Windows descarga el ejecutable y añádelo al PATH. Para iniciar el túnel hacia tu app en el puerto 3000 ejecuta: tmole 3000. Tunnelmole te mostrará una URL pública HTTPS del tipo https://subdominio.tunnelmole.net que reenvía a https://localhost:3000. Copia la URL HTTPS para configurar el webhook.

Paso 3 Configurar el webhook en Meta Entra a la consola de Meta for Developers, selecciona tu app de WhatsApp Business, ve a WhatsApp y luego Configuración. En la sección Webhooks edita la configuración e introduce como URL de devolución tu URL de Tunnelmole seguida de slash webhook, por ejemplo https://mi-subdominio.tunnelmole.net/webhook, y el mismo token de verificación que definiste en VERIFY_TOKEN. Al verificar, WhatsApp hará una solicitud GET a través del túnel; si el token coincide, tu servidor debe responder con el challenge y verás el webhook verificado.

Paso 4 Suscribirte a los campos necesarios En la pantalla de configuración del webhook pulsa Administrar y suscríbete al campo messages para recibir notificaciones de eventos de mensajería.

Paso 5 Probar de extremo a extremo Desde tu WhatsApp personal envía un mensaje al número de prueba de tu app. Observa la consola de tu servidor local y verás el payload con la información de la cuenta, el contacto y el mensaje recibido. Confirma que respondes 200 OK para que WhatsApp considere el evento entregado.

Seguridad y buenas practicas En producción valida siempre la firma de cada solicitud con el encabezado X-Hub-Signature-256 mediante HMAC SHA256 y el secreto de tu app, limita por IP si corresponde, registra eventos con niveles adecuados y protege tu VERIFY_TOKEN en variables de entorno o un gestor de secretos. Mantén HTTPS extremo a extremo y aplica principios de ciberseguridad y hardening en tus servidores.

Q2BSTUDIO a tu lado En Q2BSTUDIO diseñamos e implementamos soluciones de software a medida, aplicaciones a medida, ia para empresas y agentes IA, con estándares de ciberseguridad, servicios cloud aws y azure, y servicios inteligencia de negocio con power bi. Si buscas un partner para construir integraciones robustas con WhatsApp o automatizar procesos de punta a punta, nuestro equipo puede ayudarte desde la arquitectura hasta la puesta en producción.

Conoce cómo impulsamos proyectos de aplicaciones a medida y software a medida en nuestro servicio de desarrollo multiplataforma aquí: desarrollo de aplicaciones y software a medida. Y si la seguridad es prioritaria para tu organización, explora nuestras auditorías y pruebas de intrusión en servicios de ciberseguridad y pentesting.

Conclusion Probar webhooks suele ser un punto complejo en el desarrollo de APIs modernas. Con un túnel como Tunnelmole eliminas fricciones al obtener una URL pública instantánea para tu servidor local, verificas tu webhook en la consola de Meta y recibes eventos reales en segundos. Este flujo acelera el desarrollo, mejora la depuración y te permite construir integraciones más confiables. Si además necesitas llevar tu solución a la nube o potenciar tus datos con analítica y cuadros de mando, en Q2BSTUDIO combinamos servicios cloud aws y azure, inteligencia artificial y business intelligence para crear soluciones escalables y seguras de principio a fin.