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

> **Información:** **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 cinco 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 |
| **mTLS** | Certificado de cliente, Clave privada, CA del servidor (opcional) | Tu API solo acepta llamadas de clientes que presenten un certificado (TLS mutuo). IDCloud presenta el certificado que proporcionas en cada notificación |

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

#### Configurar mTLS

Con **mTLS**, IDCloud se identifica ante tu API presentando un certificado de cliente (TLS mutuo),
en lugar de enviar una clave, una contraseña o un token. Tu API tiene que estar configurada para
pedir ese certificado y para confiar en quien lo emitió. Al seleccionar **mTLS**, aparecen tres
campos:

| Campo | Qué proporcionar |
| :- | :- |
| **Certificado de cliente (PEM)** | La cadena de certificados en formato PEM, con el certificado hoja primero. Agrega los certificados intermedios después del tuyo, para que tu API pueda vincular el certificado con una autoridad de certificación en la que confía |
| **Clave privada (PEM)** | La clave que corresponde al certificado, en formato PEM y **sin contraseña**. Se guarda cifrada y nunca vuelve a mostrarse |
| **CA del servidor (PEM, opcional)** | Solo si el certificado de tu propia API está firmado por una autoridad de certificación privada. Sin este campo, IDCloud confía en las autoridades de certificación públicas |

Puedes elegir un archivo `.pem` o pegar el texto. Cada campo admite hasta 20.000 caracteres.

Algunas reglas que conviene conocer antes de elegir mTLS:

- **La URL tiene que ser HTTPS**, y tu API tiene que aceptar TLS 1.2 o superior.
- **Una vez guardado, el tipo queda bloqueado.** El tipo de autenticación no se puede cambiar a
  otro en esta pantalla. Para cambiar de método, contacta al soporte de Unico.
- **No se envía ninguna otra credencial.** mTLS no se puede combinar con API Key, Basic Auth ni
  OAuth 2.0 en el mismo webhook.
- **Las redirecciones cuentan como fallos.** IDCloud no las sigue, así que apunta la URL a la
  dirección final.

### 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. Con
mTLS, valida en su lugar el certificado y la clave: ambos tienen que estar en formato PEM, la
clave no puede tener contraseña y tiene que coincidir con el certificado, y el certificado tiene
que estar dentro de su período de vigencia.

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 reemplazo el certificado mTLS antes de que venza?** Edita el webhook. El certificado y la
clave privada aparecen enmascarados. Proporciona el certificado nuevo **y** la clave privada nueva
— ambos son obligatorios, aunque solo uno haya cambiado — y la CA del servidor otra vez, si usas
una. Luego guarda. IDCloud empieza a usar el certificado nuevo en un plazo de unos 5 minutos, así
que mantén vigente el certificado anterior un poco más de ese tiempo antes de revocarlo. Si dejas
los tres campos sin tocar, el certificado actual sigue en uso.

**¿Puedo cambiar de mTLS a otro tipo de autenticación?** No desde esta pantalla: después de
guardar, el tipo queda bloqueado. Contacta al soporte de Unico para quitar la configuración del
webhook y luego créala de nuevo con el método nuevo.

**¿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. Con mTLS, revisa también que tu API confíe en quien emitió el certificado, que el
certificado no haya vencido y que hayas llenado la CA del servidor si el certificado de tu API
viene de una autoridad de certificación privada. 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 | mTLS
         │                              OAuth 2.0: + URL de autenticación y Client ID
         │                              mTLS: + Certificado de cliente, Clave privada, CA del servidor (opcional)
         └─ 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
```