---
title: Configuración
description: Guía paso a paso para configurar webhooks de IDCloud — autoservicio en el portal para integraciones Web y SDK, y configuración by-client para integraciones API con orquestación Check (solo Brasil).
canonical: https://developer.unico.io/es/dual-api/developers/webhooks-and-events/setup
locale: es
generated_by: markdown-export
---

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

### Via Portal (Web & SDK)

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

#### Información requerida

| Campo | Descripción |
|---|---|
| **URL de notificación** | Endpoint al que Unico llamará para entregar notificaciones de eventos. Debe ser accesible vía HTTPS. |
| **Tipo de autenticación** | Cómo Unico se autentica contra tu endpoint. Consulta las opciones a continuación. |
| **Configuración de reintentos** | Número máximo de intentos e intervalo entre intentos (se aplica backoff exponencial). |
| **Límite de concurrencia** | Número máximo de entregas simultáneas en vuelo (máximo: **500**). |
| **Timeout** | Tiempo máximo de espera para la respuesta del endpoint, en segundos. |
| **Estados a notificar** | El 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:

| Estado | Descripción |
|---|---|
| `PROCESS_STATE_FINISHED` | Proceso finalizado — estado terminal, independientemente del resultado. |

:::warning[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.

```json
{
  "processId": "8263a268-5388-492a-bca2-28e1ff4a69f0",
  "state": "PROCESS_STATE_FINISHED",
  "flow": "id"
}
```

:::note[`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](/developers/webhooks-and-events/event-types) 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`.

:::tip[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](/developers/webhooks-and-events/security).

### By client (API — solo Brasil)

:::info[Solo Brasil]
El webhook by-client está disponible exclusivamente para integraciones API en Brasil que utilizan la capacidad de **orquestación Check** — un flujo asíncrono donde el resultado del proceso se entrega mediante webhook en lugar de como respuesta sincrónica de la API.
:::

Para registrar o actualizar tu endpoint, contacta a tu equipo de **CS / Onboarding**.

#### Información requerida

| Campo | Descripción |
|---|---|
| **URL de notificación** | Endpoint que tu sistema expone para recibir actualizaciones de estado. Debe ser accesible vía HTTPS. |
| **Tipo de autenticación** | Cómo Unico se autentica contra tu endpoint. Consulta las opciones a continuación. |
| **Configuración de reintentos** | Número máximo de intentos e intervalo entre intentos (se aplica backoff exponencial). |
| **Límite de concurrencia** | Número máximo de entregas simultáneas en vuelo (máximo: **500**). |
| **Timeout** | Tiempo máximo de espera para la respuesta del endpoint, en segundos. |

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

#### Códigos de estado

El webhook by-client utiliza **códigos de estado numéricos**:

| Código | Descripción |
|---|---|
| `2` | Divergencia — el proceso finalizó con una divergencia en la verificación de identidad. |
| `3` | Completado — el proceso finalizó correctamente. |
| `5` | Error — el proceso finalizó debido a un error. |

#### Formato de la solicitud

Las entregas de webhook son solicitudes **POST** a tu endpoint. El cuerpo contiene el identificador de la transacción y el código de estado numérico.

```json
{
  "id": "8263a268-5388-492a-bca2-28e1ff4a69f0",
  "status": 3
}
```

#### 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`.

:::tip[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.
:::

:::warning[Entrega al menos una vez]
La plataforma garantiza la entrega al menos una vez — la misma notificación puede llegar más de una vez. Implementa idempotencia de tu lado usando el campo `id` para manejar duplicados de forma segura.

Para orientación sobre idempotencia y manejo de reintentos, consulta [Seguridad](/developers/webhooks-and-events/security).
:::