Buenas prácticas en el receptor

Estas reglas valen para cualquier integración que reciba webhooks de LX CloudPos. Aplicalas siempre antes de cablear lógica de negocio sobre los eventos.

Responder rápido

Tu endpoint debe responder con un 2xx en menos de 10 segundos. Si tu procesamiento real es más largo, encolá el trabajo y respondé enseguida:

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

Como un mismo evento puede llegarte varias veces (reintentos in-process y persistentes), implementá deduplicación usando el campo nonce del payload como clave única. Ver el detalle 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

Registrá 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
});

Monitoreá fallos

Configurá alertas para:

• Tu endpoint devuelve 5xx de forma repetida.
• Recibís el mismo nonce tres o más veces (indica fallo de dedup).
• No recibís webhooks por más de 24 h (probable problema upstream o de configuración de la webhookUrl).