Saltar al contenido principal

Configuración

IDCloud admite dos modalidades de webhook, según cómo integres:

  • Via Portal — para integraciones Web y SDK. Configuración de autoservicio directamente en el portal de IDCloud.
  • By client — para integraciones API que utilizan la capacidad de orquestación Check (un flujo asíncrono). Configurado por el equipo de Unico. Disponible solo en Brasil.

Para registrar o actualizar tu endpoint de webhook, accede al portal de IDCloud y navega a Configuración > Webhook.

Información requerida​

CampoDescripción
URL de notificaciónEndpoint al que Unico llamará para entregar notificaciones de eventos. Debe ser accesible vía HTTPS.
Tipo de autenticaciónCómo Unico se autentica contra tu endpoint. Consulta las opciones a continuación.
Configuración de reintentosNúmero máximo de intentos e intervalo entre intentos (se aplica backoff exponencial).
Límite de concurrenciaNúmero máximo de entregas simultáneas en vuelo (máximo: 500).
TimeoutTiempo máximo de espera para la respuesta del endpoint, en segundos.
Estados a notificarEl 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:

EstadoDescripción
PROCESS_STATE_FINISHEDProceso 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.

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

Estos dos campos aparecen en el payload únicamente cuando result = expired — es decir, cuando el proceso expiró antes de que el usuario completara el recorrido. Están ausentes de los payloads de finalización normal. Consulta Tipos de evento para el esquema completo y la lista de posibles valores de lastEvent.

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.

Última actualización el