¿Cómo Construir APIs Basadas en Eventos con Webhooks y Colas de Mensajes?

En resumen

Las APIs basadas en eventos utilizan webhooks para notificaciones externas y colas de mensajes para procesamiento interno. Publica eventos en una cola (RabbitMQ, Kafka), procesa de forma asíncrona y notifica a los clientes a través de webhooks. Modern PetstoreAPI utiliza este patrón para el procesamiento de pedidos, actualizaciones de inventario y notificaciones de pago.

Introducción

Un cliente realiza un pedido. Tu API necesita cargar el pago, actualizar el inventario, enviar un correo electrónico, notificar al almacén y activar webhooks. ¿Haces todo esto de forma síncrona, haciendo esperar al cliente 10 segundos? ¿O respondes inmediatamente y procesas de forma asíncrona?

Las APIs basadas en eventos responden rápido y procesan en segundo plano. El endpoint de pedidos devuelve 201 Created inmediatamente. Los eventos activan el procesamiento en segundo plano. Los webhooks notifican a los clientes cuando se completa.

Modern PetstoreAPI utiliza arquitectura basada en eventos para pedidos, pagos e inventario.

Apidog te ayuda a probar webhooks, validar flujos de eventos y simular procesamiento asíncrono.

Arquitectura basada en eventos

Las APIs basadas en eventos publican eventos cuando ocurren cosas. Otros servicios se suscriben y reaccionan.

Componentes

1. Productor de Eventos - Endpoint de API que publica eventos
2. Bus/Cola de Eventos - Enruta eventos (RabbitMQ, Kafka, SQS)
3. Consumidor de Eventos - Workers en segundo plano que procesan eventos
4. Webhooks - Notifican a clientes externos

Flujo

Client → POST /orders → API
API → Publish "order.created" → Queue
API → Return 201 Created → Client
Worker → Consume event → Process order
Worker → Publish "order.completed" → Queue
Webhook Worker → Send webhook → Client

Webhooks para eventos externos

Los webhooks notifican a los clientes externos sobre los eventos.

// Publicar evento cuando se crea un pedido
app.post('/v1/orders', async (req, res) => {
  const order = await createOrder(req.body);

  await eventBus.publish('order.created', {
    orderId: order.id,
    userId: order.userId,
    total: order.total
  });

  res.status(201).json(order);
});

// Worker en segundo plano envía webhooks
eventBus.subscribe('order.completed', async (event) => {
  const webhooks = await getWebhooks(event.userId, 'order.completed');

  for (const webhook of webhooks) {
    await sendWebhook(webhook.url, {
      event: 'order.completed',
      data: event
    });
  }
});

Colas de mensajes para eventos internos

Las colas de mensajes manejan el procesamiento de eventos internos.

Ejemplo de RabbitMQ

// Publicador
await publishEvent('order.created', { orderId: '019b4132' });

// Consumidor
await consumeEvents('order.*', async (event) => {
  await processOrder(event);
});

Cómo Modern PetstoreAPI implementa APIs basadas en eventos

Procesamiento de pedidos

1. POST /orders devuelve 201 inmediatamente
2. Publica el evento order.created
3. El worker de pago procesa el pago
4. El worker de inventario actualiza el stock
5. El worker de correo electrónico envía la confirmación
6. El worker de webhook notifica al cliente

Consulta la arquitectura de eventos de Modern PetstoreAPI.

Pruebas con Apidog

Apidog admite pruebas de APIs basadas en eventos:

• Probar la entrega de webhooks
• Validar las cargas útiles de eventos
• Simular procesamiento asíncrono
• Probar la lógica de reintento

Conclusión

Las APIs basadas en eventos mejoran el rendimiento y la escalabilidad. Usa webhooks para notificaciones externas y colas de mensajes para procesamiento interno. Modern PetstoreAPI demuestra patrones basados en eventos listos para producción.

Preguntas frecuentes

¿Cuál es la diferencia entre webhooks y colas de mensajes?

Los webhooks notifican a los clientes externos a través de HTTP. Las colas de mensajes manejan la comunicación interna entre servicios.

¿Qué cola de mensajes debo usar?

RabbitMQ para simplicidad, Kafka para alto rendimiento, AWS SQS para servicio gestionado.

¿Cómo se manejan los fallos de webhook?

Implementa lógica de reintento con retroceso exponencial (consulta nuestra guía de fiabilidad de webhooks).

¿Se pueden usar eventos sin colas de mensajes?

Sí, pero las colas proporcionan durabilidad, reintentos y desacoplamiento.

¿Cómo se prueban las APIs basadas en eventos?

Usa Apidog para probar webhooks y validar flujos de eventos.