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 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