---
title: Seguridad
description: Cómo validar y proteger los payloads de webhook de IDCloud — verificación de firma y buenas prácticas.
canonical: https://developer.unico.io/es/dual-api/developers/webhooks-and-events/security
locale: es
generated_by: markdown-export
---

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.

```javascript
// 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();
}
```

:::warning[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.