Webhook

El Webhook es la forma en que IDCloud avisa a tu sistema, automáticamente, cuando algo sucede en una jornada de verificación de identidad. En lugar de que tu sistema esté preguntando "¿ya terminó?", IDCloud llama a tu API en el momento en que ocurre el evento.

En esta pantalla defines la dirección de tu API, cómo se autentica IDCloud en ella y qué pasa cuando no responde.

información

Para quién es: clientes que quieren recibir el resultado de las jornadas automáticamente, sin consultar. Aplica tanto para integraciones byUnico como byClient.

Qué cambia en tu sistema: pasa a recibir una notificación en cada cambio de estado, en lugar de tener que consultar a IDCloud.

Dónde está: Portal IDCloud → menú lateral Configuraciones → pestaña Webhook.

Antes de que existiera esta pantalla, cualquier cambio de webhook requería abrir un ticket — eran alrededor de 30 tickets al mes solo por eso. Ahora lo haces tú mismo, en minutos, tanto en Homologación como en Producción.

Antes de empezar

Permiso de acceso

Tu usuario necesita tener el perfil de Configurador — el mismo que da acceso a la Personalización de la Jornada. Si la pestaña Webhook no aparece, habla con el administrador de tu cuenta.

Cómo se aplica la configuración

Alcance	Un webhook por tenant y unidad (branch). No existe una lista: si ya hay uno configurado, se edita, no se duplica.
Ambientes separados	El Portal de Homologación configura el webhook de UAT; el de Producción, el de Producción. Configurar uno no afecta al otro.
Cuándo entra en vigencia	En cuanto guardas.
Seguridad del secret	El secret está cifrado y nunca vuelve a mostrarse en texto plano. En la pantalla siempre aparece enmascarado.

Qué tener a la mano

• La URL HTTPS de tu API que va a recibir las notificaciones. Debe estar activa y aceptando solicitudes antes de guardar.
• Las credenciales que tu API espera, según el método de autenticación elegido (ver Paso 3).
• Si tu API tiene un límite de capacidad, el número de solicitudes por segundo que soporta.

Qué decidir antes

Dos decisiones técnicas dependen de quien mantiene tu API, no de quien opera el Portal. Vale la pena alinearlas antes de abrir la pantalla:

• Qué método de autenticación requiere tu API.
• Si vas a ajustar los reintentos o dejarlos en el valor predeterminado. El predeterminado funciona para la mayoría de los casos.

Paso a paso

Paso 1 — Abre la pestaña Webhook

En el Portal IDCloud, haz clic en el ícono de engranaje (Configuraciones) en el menú lateral y selecciona la pestaña Webhook.

Si aún no tienes un webhook configurado, la pantalla muestra "No se han creado webhooks" y un botón Crear webhook. Si ya tienes uno, la pantalla muestra la tarjeta Tu webhook con el endpoint, el tipo de autenticación y el secret enmascarado, además del botón Configurar webhook para editarlo.

Tarjeta "Tu webhook" con endpoint, tipo de autenticación y secret enmascarado.

Paso 2 — Indica la URL de tu API

Haz clic en Crear webhook (o Configurar webhook, si ya existe uno) y llena el campo URL del cliente (Endpoint), en "Información del cliente".

Es la dirección a la que IDCloud enviará las notificaciones. Debe ser HTTPS.

Apunta a una dirección que ya esté activa. IDCloud empieza a llamar a esta URL en cuanto guardas. Si aún no existe, las primeras notificaciones fallarán y consumirán los reintentos antes de que tu equipo lo note.

Campo de endpoint, con el texto de apoyo sobre el requisito de HTTPS.

Paso 3 — Elige cómo se autentica IDCloud en tu API

En "Autenticación", selecciona el Tipo de autenticación. Hay cuatro opciones, y cada una pide campos distintos:

Tipo	Campos que aparecen	Cuándo usarlo
Ninguna	ninguno	Tu API no requiere autenticación. Úsalo solo si tiene otra protección — sin autenticación, cualquiera que descubra la URL puede enviarle datos
API Key	Secret	Tu API valida una clave fija
Basic Auth	Secret	Tu API usa usuario y contraseña, estilo HTTP Basic
OAuth 2.0	URL de autenticación, Client ID, Secret	Tu API requiere un token. IDCloud obtiene el token de esa URL y lo renueva solo

En OAuth 2.0, la URL de autenticación es la dirección donde IDCloud obtiene el token — no es la URL que recibe las notificaciones. Son direcciones distintas, y confundirlas es el error más común en esta pantalla.

El Secret se guarda cifrado. Al editar un webhook existente, el campo aparece vacío: llenarlo sobrescribe el secret actual, y dejarlo en blanco mantiene el que ya estaba.

Confirma el método con quien mantiene tu API antes de guardar. Una autenticación incorrecta no genera un error en la pantalla — genera una notificación que falla silenciosamente después, y solo te enteras cuando un resultado no llega.

Campo Tipo de autenticación y los campos de credencial correspondientes.

Paso 4 — Ajusta los reintentos, si es necesario

La sección Configuración de reintentos es opcional y viene apagada. Actívala solo si necesitas cambiar el comportamiento predeterminado.

Al activarla, aparecen seis campos:

Campo	Qué controla	Predeterminado
Máximo de reintentos	Cuántas veces IDCloud vuelve a intentar antes de rendirse	—
Límite de tasa (req/s)	Máximo de notificaciones por segundo. Redúcelo si tu API tiene capacidad limitada	—
Tiempo mínimo (s)	Intervalo mínimo entre intentos	2s
Tiempo máximo (s)	Intervalo máximo entre intentos	10s
Duración máxima (s)	Tiempo de espera por intento antes de considerarlo un fallo	2s
Duplicaciones máximas	Factor de crecimiento del intervalo entre intentos (backoff)	5

El comportamiento combinado es: IDCloud intenta, espera el tiempo mínimo, intenta de nuevo, y va aumentando el intervalo según las duplicaciones máximas hasta el tiempo máximo — repitiendo hasta el máximo de reintentos. Cada intento individual se rinde después de la duración máxima.

Ajusta el Límite de tasa antes de tocar el resto. Si tu API se cae bajo carga, el problema es de capacidad, no de reintentos — y aumentar los reintentos en ese escenario lo empeora, porque multiplica las llamadas. Reduce la tasa primero.

Aumentar el Máximo de reintentos no sustituye una API estable. Los reintentos cubren indisponibilidad momentánea. Si tu API falla con frecuencia, este ajuste solo retrasa el momento en que pierdes la notificación.

Los seis campos de reintentos, mostrados al activar el selector.

Paso 5 — Guarda

Haz clic en Guardar. Cancelar descarta todo y mantiene la configuración anterior.

IDCloud valida la URL del token antes de permitir guardar, cuando el método es OAuth 2.0.

Después de guardar, la tarjeta Tu webhook muestra el endpoint y el tipo de autenticación. El secret aparece enmascarado y ya no se puede recuperar desde la pantalla — si pierdes el valor, necesitas registrar uno nuevo.

Haz una prueba real antes de darlo por terminado. Inicia una jornada en Homologación y confirma que la notificación llegó a tu API. La pantalla confirma que la configuración se guardó, no que tu API la recibió.

Preguntas frecuentes

¿Puedo registrar más de un webhook? No. Es un webhook por tenant y unidad. Si ya existe uno, se edita — no hay forma de crear un segundo.

Lo configuré en Homologación. ¿Ya aplica para Producción? No. Los ambientes son independientes: el Portal de Homologación configura el webhook de UAT, y el de Producción configura el de Producción. Debes repetir la configuración en el Portal de Producción.

¿Cómo veo el secret que registré? No es posible. Se cifra al guardar y siempre se muestra enmascarado. Si perdiste el valor, registra uno nuevo desde el campo Secret — llenarlo sobrescribe el anterior.

Edité el webhook pero no quiero cambiar el secret. ¿Qué hago? Deja el campo Secret en blanco. El valor actual se mantiene.

¿Cómo elimino un webhook? La pantalla no ofrece eliminación. Para quitar la configuración, contacta al soporte de Unico. Si el objetivo es solo dejar de recibir o cambiar el destino, edita la URL.

Guardé y las notificaciones no llegan. Revisa, en este orden: la URL es correcta y es HTTPS; tu API está activa; el método de autenticación es el que espera; y el secret se escribió correctamente. Un fallo de autenticación no aparece como error en esta pantalla — ocurre en la entrega.

¿Cuál es la diferencia entre "Duración máxima" y "Tiempo máximo"? "Tiempo máximo" es el mayor intervalo de espera entre dos intentos. "Duración máxima" es cuánto espera IDCloud por un intento antes de considerarlo un fallo.

¿Necesito un webhook si ya consulto el resultado por la API? No es obligatorio, pero evita que tu sistema esté consultando. Si ya tienes una rutina de consulta funcionando, el webhook es una optimización, no un requisito.

Resumen rápido

Portal IDCloud
 └─ Configuraciones (ícono de engranaje en el menú lateral)
     └─ Pestaña Webhook
         ├─ Información del cliente ... URL del cliente (Endpoint), HTTPS
         ├─ Autenticación .............. Ninguna | API Key | Basic Auth | OAuth 2.0
         │                              OAuth 2.0: + URL de autenticación y Client ID
         └─ Reintentos (opcional) ..... Máximo de reintentos
                                        Límite de tasa (req/s)
                                        Tiempo mínimo (2s) · Tiempo máximo (10s)
                                        Duración máxima (2s) · Duplicaciones máximas (5)

Un webhook por tenant y unidad · UAT y Producción independientes · Secret nunca visible · Cancelar · Guardar