Receiver best practices

These rules apply to any integration that receives webhooks from LX CloudPos. They must always be applied before building business logic on top of the events.

Respond quickly

The endpoint must respond with a 2xx in under 10 seconds. If the actual processing takes longer, queue the work and send the response immediately:

app.post('/webhooks/lxs', verificarHmac, async (req, res) => {
  const evento = JSON.parse(req.body.toString('utf8'));
 
  // Queue in the background and respond immediately
  await queue.add('procesar-evento-lxs', evento);
 
  res.status(200).end();
});

Receiver idempotency

Since the same event may be received more than once (in-process and persistent retries), you must implement deduplication using the payload’s nonce field as the unique key. See deduplication for details.

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 } }),
    // ... your business logic
  ]);
}

Logging

Log every webhook received (after verifying the signature) with structured fields for auditing and troubleshooting:

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

Failure monitoring

Configure alerts for the following cases:

• The endpoint repeatedly returns 5xx.
• The same nonce is received three or more times (indicates a dedup failure).
• No webhooks are received for more than 24 hours (likely an upstream issue or a webhookUrl configuration problem).