--- title: Webhook description: Configura hacia dónde notifica IDCloud a tu sistema cuando una jornada cambia de estado, cómo se autentica en tu API y qué pasa cuando tu API no responde. canonical: https://developer.unico.io/es/dual-api/product-guide/portal-idcloud/settings/webhook locale: es generated_by: markdown-export --- 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. :::info **Para quién es:** clientes que quieren recibir el resultado de las jornadas automáticamente, sin consultar. Aplica para todos los tipos de integración. **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 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 Administra tu webhook, con el botón Configurar webhook](/img/product-guide/webhook/es/01-manage-webhook.png) *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](/img/product-guide/webhook/es/02-edit-webhook.png) *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](/img/product-guide/webhook/es/02-edit-webhook.png) *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](/img/product-guide/webhook/es/02-edit-webhook.png) *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 ```text 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 ```