Seguridad

La confiabilidad de los webhooks depende tanto del comportamiento de tu endpoint como de las garantías de entrega de Unico. Esta página cubre los tres invariantes que tu endpoint debe respetar: idempotencia, límite de concurrencia y tasa de errores.

Idempotencia

La implementación de webhooks de Unico garantiza una entrega al menos una vez — el mismo estado puede ser notificado más de una vez para el mismo processId. Tu endpoint debe ser idempotente.

Patrón recomendado:

1. En cada llamada de webhook, verifica primero si el processId ya fue procesado.
2. Si fue procesado, retorna 2xx inmediatamente (el trabajo ya está hecho).
3. Si no, aplica tu lógica de negocio y persiste el hecho de que este processId fue procesado.

// pseudo-code
async function handleWebhook(req, res) {
  const { processId } = req.body;

  if (await alreadyProcessed(processId)) {
    return res.status(200).end();
  }

  await applyBusinessLogic(req.body);
  await markAsProcessed(processId);
  return res.status(200).end();
}

Por qué esto importa

Un endpoint no idempotente que ejecuta lógica de negocio en cada entrega (p. ej., carga una tarjeta, envía un correo electrónico) se disparará múltiples veces cuando ocurra un reintento — y los reintentos son normales, no excepcionales, en la entrega de webhooks.

Límite de concurrencia

Para proteger tu endpoint de picos durante períodos de alto volumen, configura un número máximo de entregas simultáneas en vuelo (máximo: 500) al registrar el webhook.

Cuando se alcanza el límite de concurrencia, Unico pone en cola las entregas adicionales y las procesa a medida que la capacidad esté disponible. Combinado con los reintentos, esto significa que un pico sostenido puede extender el tiempo de entrega efectivo de los nuevos webhooks.

Tasa de errores

La tasa de errores (respuestas fuera del rango 200–299) siempre debe ser baja. Si tu endpoint comienza a retornar errores a escala, Unico reduce automáticamente el rendimiento del webhook para ese endpoint. Combinado con el mecanismo de reintentos, esto puede aumentar significativamente el tiempo de ejecución de los nuevos webhooks.

Guía operacional:

• Monitorea las respuestas no 2xx de tu lado. Genera alertas cuando las tasas de error sostenidas superen tu línea de base normal.
• Trata tu manejador de webhooks como una ruta crítica — debe ser uno de los servicios más confiables de tu stack.
• Para el mantenimiento planificado, prefiere detener la ingesta en el load balancer en lugar de retornar 503. Las respuestas no 2xx sostenidas — incluyendo 503 — activan el throttling automático de rendimiento descrito anteriormente; cuando tu endpoint se recupera, el rendimiento reducido retrasa la entrega de los eventos que se acumularon durante la interrupción. No retornes 200 para eventos no procesados.

Semántica de estados

Trata el conjunto de valores de state y lastEvent como configuración evolutiva:

• Reacciona solo a los estados / eventos que manejas explícitamente.
• Registra los valores desconocidos — no generes errores por ellos.
• Nuevos estados pueden agregarse sin un cambio de versión mayor.