Buenas prácticas en el receptor

Estas reglas aplican a cualquier integración que reciba webhooks de LX CloudPos. Deben aplicarse siempre antes de construir lógica de negocio sobre los eventos.

Responder rápido

El endpoint debe responder con un 2xx en menos de 10 segundos. Si el procesamiento real requiere más tiempo, el trabajo debe encolarse y la respuesta debe emitirse de inmediato:

app.post('/webhooks/lxs', verificarHmac, async (req, res) => {
  const evento = JSON.parse(req.body.toString('utf8'));
 
  // Encola en background y responde inmediatamente
  await queue.add('procesar-evento-lxs', evento);
 
  res.status(200).end();
});

Idempotencia del receptor

Dado que un mismo evento puede recibirse varias veces (reintentos in-process y persistentes), debe implementarse la deduplicación utilizando el campo nonce del payload como clave única. El detalle se encuentra en deduplicación.

async function procesarEvento(evento) {
  const yaProcesado = await db.eventosLxs.findUnique({ where: { nonce: evento.nonce } });
  if (yaProcesado) return;
 
  await db.$transaction([
    db.eventosLxs.create({ data: { nonce: evento.nonce, payload: evento } }),
    // ... tu lógica de negocio
  ]);
}

Logging

Debe registrarse cada webhook recibido (después de verificar la firma) con campos estructurados para auditoría y troubleshooting:

logger.info('Webhook LX recibido', {
  evento: evento.evento,
  clave: evento.clave,
  ind_estado: evento.ind_estado,
  intento: evento.intento,
  nonce: evento.nonce
});

Monitoreo de fallos

Deben configurarse alertas para los siguientes casos:

• El endpoint devuelve 5xx de forma repetida.
• Se recibe el mismo nonce tres o más veces (indica fallo de dedup).
• No se reciben webhooks durante más de 24 h (probable problema upstream o de configuración de la webhookUrl).