Manejador de webhooks de video tolerante a duplicados (Express + Postgres)

En el ecosistema actual de aplicaciones basadas en video, la recepción de webhooks asíncronos se ha convertido en un pilar fundamental para garantizar que los flujos de trabajo de codificación, transcodificación y entrega se ejecuten sin contratiempos. Sin embargo, uno de los desafíos más sutiles y peligrosos es la naturaleza 'al menos una vez' de estos eventos: el proveedor puede reenviar el mismo webhook varias veces si no recibe una confirmación rápida. Un diseño ingenuo puede provocar que el video se suba y codifique correctamente, pero nunca aparezca en la interfaz del usuario, sin que ningún error sea reportado. Para evitarlo, es imprescindible construir un manejador tolerante a duplicados, con verificación de integridad y procesamiento asíncrono.

El primer paso crítico es preservar el cuerpo crudo de la petición. Muchos middlewares de parseo JSON, como el global express.json(), consumen el buffer original y re-serializan el objeto, rompiendo cualquier verificación de firma HMAC-SHA256. La solución es montar un middleware express.raw() exclusivamente en la ruta del webhook, antes de cualquier otro parseo, y mantener el JSON normal para el resto de la API. Así se garantiza que la firma se calcula sobre los mismos bytes que envió el proveedor, y se puede comparar en tiempo constante con crypto.timingSafeEqual para no filtrar la clave secreta. Además, conviene validar un timestamp en el encabezado para protegerse contra ataques de repetición.

Una vez autenticado el evento, hay que lidiar con los duplicados. Un índice único en Postgres sobre el event_id proporcionado por el proveedor convierte cualquier inserción duplicada en un no-op gracias a INSERT ... ON CONFLICT DO NOTHING. Al devolver un 200 inmediato después de persistir, se evita que el proveedor reintente; si el evento ya existía, se responde igualmente con 200 y se descarta. Este mecanismo de idempotencia es la base para que el sistema sea robusto ante reintentos y caídas de red.

El procesamiento pesado debe delegarse a una cola (por ejemplo, SQS, BullMQ o RabbitMQ) para no superar los tiempos de espera típicos de 5 a 15 segundos. El endpoint solo verifica, persiste, encola y responde 202. Un trabajador independiente consume los mensajes, ejecuta la lógica de negocio (marcar el asset como listo, actualizar la base de datos, etc.) y actualiza el campo processed. Esto permite manejar errores de negocio con reintentos propios y una cola de mensajes fallidos (dead-letter queue), en lugar de devolver un 500 que provocaría reintentos infinitos del proveedor.

Otro error común es tratar los webhooks como única fuente de verdad. Si el servicio estuvo caído durante una hora, los eventos perdidos pueden no recuperarse. Por ello, es recomendable implementar un trabajo periódico de reconciliación que liste los assets desde la API del proveedor y compare con el estado local, para re-procesar cualquier evento faltante. Esta estrategia es similar a la que se emplea en sistemas de mensajería confiables y puede integrarse con servicios cloud AWS y Azure para escalar sin esfuerzo.

En Q2BSTUDIO, como empresa de desarrollo de software a medida, aplicamos estos patrones en proyectos que requieren alta disponibilidad y tolerancia a fallos. Nuestros equipos combinan buenas prácticas de ciberseguridad, inteligencia artificial para empresas y agentes IA que analizan flujos de video en tiempo real, todo soportado por una infraestructura cloud robusta. Además, integramos servicios de inteligencia de negocio con Power BI para monitorizar la salud de los pipelines y generar alertas ante anomalías. Si necesitas construir un sistema de procesamiento de eventos asíncronos fiable, desde aplicaciones a medida hasta soluciones completas de automatización, podemos ayudarte a diseñar e implementar la capa de manejo de webhooks que tu negocio requiere.