Construyendo una plataforma de trabajos asíncronos con BullMQ, Socket.io y Webhooks

La construcción de sistemas distribuidos que gestionan trabajos asíncronos con garantías de entrega y escalabilidad real supone un reto técnico considerable. En entornos donde la separación de procesos, la tolerancia a fallos y la comunicación en tiempo real son requisitos fundamentales, tecnologías como BullMQ, Socket.io y un diseño basado en colas y eventos ofrecen soluciones maduras. Este artículo explora los principios arquitectónicos detrás de una plataforma de orquestación de trabajos asincrónicos, analizando decisiones clave como el uso de Redis como bus de mensajes, PostgreSQL como fuente de verdad, y la implementación de webhooks con firma HMAC, reintentos exponenciales y circuit breakers a nivel de aplicación.

La separación de procesos es uno de los pilares: el servidor API que expone endpoints REST y WebSockets corre de forma independiente al proceso worker que ejecuta las tareas. Comparten estado únicamente a través de Redis y la base de datos, evitando acoplamiento. Esto permite escalar horizontalmente cada componente por separado, exactamente igual que en un despliegue con Kubernetes. El patrón de comunicación entre procesos se resuelve mediante el adaptador de Redis para Socket.io, permitiendo que el worker emita eventos hacia los clientes conectados al API sin necesidad de una conexión directa. Es una arquitectura que cualquier empresa que ofrezca aplicaciones a medida puede adoptar para garantizar fiabilidad y rendimiento.

El ciclo de vida de un trabajo comienza con una petición POST validada con Zod, que registra el trabajo en PostgreSQL con estado QUEUED, lo encola en BullMQ y devuelve un 202 Accepted. El worker recoge el trabajo, actualiza el estado a RUNNING, ejecuta el handler correspondiente y, al finalizar, persiste el resultado y dispara un webhook. Si falla, BullMQ reintenta con backoff exponencial hasta agotar el número máximo de intentos. Los clientes nunca necesitan hacer polling: se conectan por WebSocket a una sala específica del trabajo y reciben en tiempo real cada transición de estado. Este patrón es ideal para servicios de inteligencia artificial o procesamiento de archivos donde el usuario necesita feedback inmediato sin sobrecargar el servidor.

La entrega de webhooks presenta desafíos adicionales. Cada payload se firma con HMAC-SHA256 usando la clave secreta del webhook, permitiendo que el receptor verifique la integridad y autenticidad. Las entregas fallidas se reintentan con retardos exponenciales (2s, 4s, 8s…), y tras cinco fallos se marcan como fallidas permanentemente. Pero además, se implementa un circuit breaker sobre Redis que, tras cinco fallos consecutivos a la misma URL, abre el circuito durante cinco minutos, evitando peticiones inútiles a un endpoint caído. Este patrón, típico de mallas de servicio en producción, se implementa aquí a nivel de aplicación sin sidecars. Cuando se requiere ia para empresas o sistemas de notificaciones críticas, estas estrategias de resiliencia son imprescindibles.

La idempotencia se resuelve mediante el encabezado Idempotency-Key, que permite repetir una misma petición sin efectos secundarios. El middleware hashea la clave junto con el ID de usuario, consulta si ya existe una respuesta almacenada y, en caso afirmativo, la devuelve sin ejecutar el handler. Si no, tras ejecutar el handler, intercepta la respuesta y la guarda en PostgreSQL. Este mismo patrón que usa Stripe para pagos es aplicable a cualquier sistema que maneje operaciones críticas, desde carga de archivos hasta procesamiento de pagos. En este contexto, los agentes IA que requieren múltiples pasos asíncronos se benefician enormemente de estas garantías.

El pipeline de subida de archivos sigue una arquitectura asíncrona similar: el cliente envía el archivo como multipart, el API lo almacena a través de un proveedor abstracto (LocalStorage o S3), registra el archivo en base de datos, encola un trabajo de procesamiento y devuelve 202. El worker extrae metadatos (MIME, dimensiones, número de páginas) y dispara un webhook al finalizar. La abstracción del almacenamiento permite cambiar de disco local a servicios cloud aws y azure simplemente modificando una variable de entorno, sin tocar el resto del código. Este nivel de flexibilidad es fundamental en entornos empresariales donde se necesitan software a medida que evolucionen con la infraestructura.

La autenticación se basa en claves API almacenadas como hash SHA-256, nunca en texto plano. Cada petición calcula el hash de la clave recibida y busca en PostgreSQL. El rate limiting se implementa con una ventana deslizante sobre Redis: cada solicitud incrementa un contador con TTL de 60 segundos, y al superar 100 peticiones por minuto se devuelve 429 Too Many Requests con cabeceras estándar. La versión de la API se añade mediante middleware, lo que permite deprecaciones graduales. Todo esto se integra de manera natural en un pipeline CI/CD que incluye linter, compilación TypeScript, tests con contenedores de servicio, build de imágenes Docker y escaneo de vulnerabilidades. Para empresas que necesitan ciberseguridad y soluciones robustas, este enfoque minimiza riesgos.

En Q2BSTUDIO, entendemos que estas arquitecturas no son solo teoría. Nuestro equipo combina experiencia en servicios inteligencia de negocio con Power BI, inteligencia artificial y automatización de procesos para construir plataformas que ejecutan millones de trabajos al día. Desde la implementación de colas de mensajería hasta la orquestación de agentes IA, ofrecemos soluciones modulares, testables y listas para producción. Si buscas transformar tu infraestructura hacia un modelo basado en eventos con garantías de entrega y escalabilidad real, podemos ayudarte a diseñar e implementar un sistema a la medida de tus necesidades.