Configuración

Para configurar un webhook en Unico IDCloud, proporciona tu endpoint, el método de autenticación y la política de reintentos. La configuración es realizada por el equipo de Unico — contacta a tu equipo de CS / Onboarding para registrar o actualizar un webhook.

Información requerida

Campo	Descripción
URL de notificación	Endpoint al que Unico llamará para entregar notificaciones de eventos. Debe ser accesible vía HTTPS.
Tipo de autenticación	Cómo Unico se autentica contra tu endpoint. Consulta las opciones a continuación.
Configuración de reintentos	Número máximo de intentos e intervalo entre intentos (se aplica backoff exponencial).
Límite de concurrencia	Número máximo de entregas simultáneas en vuelo (máximo: 500).
Timeout	Tiempo máximo de espera para la respuesta del endpoint, en segundos.
Estados a notificar	El conjunto de estados del proceso que disparan una notificación. Actualmente fijo en PROCESS_STATE_FINISHED; no es configurable en este momento.

Métodos de autenticación

OAuth2

Proporciona:

• endpoint del webhook
• URL del proveedor OAuth2
• ClientId del proveedor OAuth2
• Secret del proveedor OAuth2

Unico solicitará un token de acceso al URL del proveedor usando las credenciales del cliente y lo reenviará a tu endpoint como token Bearer.

Autorización básica

Proporciona credenciales en el formato user:pass. Unico las codifica en Base64 y las envía en el encabezado Authorization: Basic <encoded> en cada llamada de webhook.

API Key

Se admiten dos formatos. La cadena se divide en el primer signo de dos puntos:

• header:value — establece un nombre de encabezado personalizado. Ejemplos:
  • X-API-Key:abc123 → X-API-Key: abc123
  • Authorization:Bearer abc123 → Authorization: Bearer abc123
• Solo value (sin dos puntos) — el valor se envía como encabezado Authorization sin prefijo de esquema. Ejemplo: abc123 → Authorization: abc123.

Usa el formato header:value cuando necesites un esquema Bearer (p. ej., Authorization:Bearer <token>); el formato de solo valor envía el valor sin prefijo.

Sin autenticación

No se envían credenciales. Solo se recomienda para entornos de desarrollo — los endpoints de producción siempre deben requerir autenticación.

Estados del proceso que disparan notificaciones

Actualmente, Unico envía una notificación cada vez que un proceso transiciona a:

Estado	Descripción
PROCESS_STATE_FINISHED	Proceso finalizado — estado terminal, independientemente del resultado.

Los estados pueden evolucionar

El conjunto de estados notificados por la plataforma puede cambiar en el futuro. Haz que los estados a los que reacciona tu endpoint sean configurables, de modo que agregar un nuevo estado no requiera redesplegar tu servicio.

Formato de la solicitud

Las entregas de webhook son solicitudes POST a tu endpoint. El cuerpo contiene el identificador del proceso y el estado actual. Todos los campos son obligatorios.

{
  "processId": "8263a268-5388-492a-bca2-28e1ff4a69f0",
  "state": "PROCESS_STATE_FINISHED",
  "flow": "id",
  "lastEvent": "EVENT_TYPE_PROCESS_CREATED",
  "lastEventDescription": "Process created"
}

Para el esquema completo del payload y la lista de valores de lastEvent, consulta Tipos de evento.

Respuesta esperada

Tu endpoint debe responder sincrónicamente:

• Éxito: cualquier estado HTTP en el rango 200–299.
• Falla: cualquier otro estado. Unico reintentará con backoff exponencial hasta el número máximo configurado de intentos, o hasta que reciba un 2xx.

Responde rápido

Acepta el webhook rápidamente (dentro de tu timeout configurado) y procesa el payload de forma asíncrona de tu lado. El procesamiento de larga duración dentro del manejador de webhooks aumenta la probabilidad de timeouts y reintentos innecesarios.

Para orientación sobre idempotencia y manejo de reintentos, consulta Seguridad.