GET de verificación y POST de eventos cumplen funciones diferentes
Durante la configuración Meta valida el endpoint mediante el mecanismo de challenge y el verify token definido por tu aplicación. Esa verificación inicial no sustituye la seguridad de los eventos posteriores. Trata ambos flujos por separado y evita registrar secretos completos en logs.
El endpoint debe ser público mediante HTTPS y responder de forma predecible. No coloques autenticación interactiva, CAPTCHA o redirecciones delante de la ruta del webhook.
Verifica que el POST proviene de la fuente esperada
Valida la firma x-hub-signature-256 utilizando el secreto de la aplicación y el cuerpo crudo de la solicitud. La validación debe ocurrir antes de confiar en el contenido. Si tu framework transforma el JSON antes de calcular la firma, conserva acceso al raw body.
No utilices el verify token como si fuera la firma de eventos. Son mecanismos distintos. Protege el app secret en un gestor de secretos y rota credenciales según tu política.
Responde rápido y procesa después
El webhook no debería ejecutar consultas lentas, llamadas a IA, envío de correo o lógica pesada antes de devolver éxito. Valida, normaliza lo mínimo, persiste el evento o colócalo en una cola y responde. El worker procesa después. Esto reduce timeouts y duplicados derivados de reintentos.
Conserva un identificador idempotente. Los sistemas de eventos pueden repetir entregas; procesar dos veces un cambio de estado o un mensaje puede duplicar automatizaciones, leads o notificaciones.
Qué registrar sin convertir los logs en una copia de las conversaciones
Registra event ID o message ID, WABA/Phone Number ID, tipo de evento, timestamp, estado de procesamiento, latencia y error técnico. Enmascara o minimiza datos personales. Los logs deben permitir diagnosticar un incidente sin almacenar indefinidamente el cuerpo completo de todas las conversaciones.
Crea métricas de tasa de éxito, retraso de cola, duplicados, eventos descartados y errores por tipo. Una alerta basada únicamente en HTTP 500 detecta demasiado tarde muchos problemas.
Patrón de arquitectura recomendado para producción
Un patrón robusto es Meta → endpoint HTTPS → validación de firma → persistencia/cola → HTTP 200 → worker → CRM/bot/automatización. El request web termina pronto; el worker puede reintentar sin obligar a Meta a repetir el evento. Guarda un hash o ID de idempotencia antes de ejecutar efectos externos.
Para alta disponibilidad, ejecuta varios consumidores sobre la misma cola con una política de locking o partición por conversación. Así preservas orden lógico cuando es necesario sin convertir todo el procesamiento en una única fila global.
Define una dead-letter queue para eventos que exceden los reintentos. Un operador debe poder inspeccionarlos y reinyectarlos después de corregir la causa, conservando trazabilidad.
Pruebas que casi nunca se hacen y luego causan incidentes
Reenvía exactamente el mismo payload dos veces y confirma que no se duplica el lead. Envía eventos fuera de orden y comprueba que un estado antiguo no sobrescribe uno más reciente. Simula caída del CRM y verifica que el webhook sigue respondiendo después de encolar. Prueba una firma inválida y confirma que se rechaza sin filtrar el secreto.
Mide tiempo desde recepción hasta acción final. Una cola “saludable” puede estar acumulando cinco minutos de retraso sin devolver errores HTTP. Para atención comercial, esa latencia sí importa.
Tabla práctica para tomar decisiones
| Capa | Responsabilidad | Fallo típico |
|---|---|---|
| Endpoint | Aceptar HTTPS y validar solicitud | Timeout o ruta protegida por WAF |
| Verificación | Responder challenge correcto | Verify token inconsistente |
| Autenticidad | Validar x-hub-signature-256 | Calcular sobre JSON reserializado |
| Cola | Desacoplar procesamiento | Procesar IA antes del 200 |
| Worker | Aplicar lógica idempotente | Duplicar acciones por reintentos |
Checklist antes de llevarlo a producción
- El endpoint HTTPS es accesible sin desafíos interactivos.
- La firma se calcula sobre el cuerpo crudo.
- El procesamiento pesado ocurre fuera del request principal.
- Los eventos repetidos no producen acciones duplicadas.
- Hay métricas de latencia, errores y backlog.
Integra WhatsApp API con una arquitectura mantenible
Optimify documenta y opera integraciones de WhatsApp API conectadas con CRM, chat y automatizaciones empresariales.
Consultar documentación de OptimifyPreguntas prácticas que suelen aparecer al implementar este tema
¿Por qué recibo el mismo evento más de una vez?
Los sistemas de webhooks pueden reintentar entregas. La aplicación debe ser idempotente: identificar que el evento o efecto ya fue procesado y no crear otra venta, lead o respuesta. Diseña pensando en entrega al menos una vez, no en “exactamente una”.
¿Debo responder 200 antes de procesar el mensaje?
La práctica robusta es validar y asegurar el evento de forma rápida, devolver éxito y procesar trabajo pesado en una cola. Si necesitas completar todo antes de responder, aumentas timeout, reintentos y acoplamiento con servicios externos.
¿Qué hago si el CRM está caído?
El webhook debe poder conservar el evento en una cola duradera y reintentar posteriormente. La caída de un sistema downstream no debería hacer que pierdas mensajes o fuerce a Meta a actuar como tu sistema de reintentos interno.