> ## Documentation Index
> Fetch the complete documentation index at: https://developers.argosidentity.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Webhook
> Arquitectura de comunicación de red y políticas de seguridad del canal Webhook mediante el cual ARGOS Identity notifica los resultados de verificación a las organizaciones clientes.
## 1. Descripción general del documento
### 1.1 Propósito
Este documento es un recurso que resume la arquitectura de comunicación de red y las políticas de seguridad del canal mediante el cual ARGOS Identity notifica los resultados de verificación a las organizaciones clientes de forma **Webhook (callback)**.
### 1.2 Destinatarios
* Responsables de revisión de seguridad e información de las organizaciones clientes
* Equipos de desarrollo que construyen y operan endpoints receptores de Webhook
* Departamentos de cumplimiento normativo / auditoría
### 1.3 Alcance
* Comunicación de envío de Webhook en dirección ARGOS → cliente
* Protocolo de comunicación, TLS, cifrado de payload
* Autenticación, integridad, reintentos y auditoría
***
## 2. Introducción a la categoría de servicio
**Webhook** es el canal mediante el cual ARGOS notifica de forma **asíncrona** los resultados del procesamiento KYC (aprobado / rechazado / incompleto, etc.) a las organizaciones clientes.
### 2.1 Características
* **Basado en eventos**: envío inmediato en el momento en que se genera el resultado (sin necesidad de polling)
* **Conformidad con el estándar HTTPS**: las organizaciones clientes pueden recibir en un servidor HTTP estándar sin necesidad de instalar un SDK adicional
* **Estructura de pipeline de 2 etapas**:
1. **Capa de convergencia de eventos** (serverless): decisión del destinatario de envío + composición del cuerpo
2. **Capa de ejecución de envío** (servidor de envío dedicado): ejecución de HTTPS POST hacia el endpoint del cliente
### 2.2 Disparadores de envío
| Evento | Momento de envío |
| -------------------------------- | --------------------------------------------------------------------------------- |
| Verificación completada | Inmediatamente después de la confirmación del resultado en Liveform / Restful API |
| Cambio de estado de verificación | Cuando se genera una solicitud de reverificación o una solicitud de complemento |
| Acción del administrador | Cuando se produce una acción manual de aprobación/rechazo en el dashboard |
***
## 3. Flujo de comunicación de red
### 3.1 Flujo completo
```mermaid theme={null}
flowchart TD
K[Resultado de verificación KYC confirmado] -->|Llamada AWS
SigV4| C["Capa de convergencia de eventos Webhook
- Consulta de opciones del proyecto
- Composición del cuerpo de envío
- Aplicación de opción de cifrado (opcional)"]
C -->|Llamada AWS| S[Capa de ejecución de envío Webhook]
S -->|HTTPS POST
TLS 1.2+| E[Endpoint receptor Webhook del cliente]
E -->|HTTP 200 OK / Non-2xx| L[Registro de auditoría del resultado de envío]
```
### 3.2 Canal de transmisión externo
| Elemento | Valor |
| --------------------------- | ------------------------------------------------------------------------------------------- |
| Dirección | ARGOS → cliente (Outbound from ARGOS) |
| Protocolo | HTTPS (TLS 1.2 o superior obligatorio) |
| HTTP Method | POST (configurable según ajuste del cliente) |
| Content-Type | `application/json` (por defecto) / `text/plain` (cuando la opción de cifrado está activada) |
| Verificación de certificado | ARGOS verifica el certificado del cliente (rejectUnauthorized activado) |
***
## 4. Protocolos y normas de comunicación
### 4.1 Capa de transporte
* **TLS 1.2 o superior** (imposición explícita en el HTTPS Agent: `secureProtocol: TLSv1_2_method`)
* El certificado del servidor del cliente se verifica mediante la cadena de confianza PKI estándar (Root CA)
* Los certificados autofirmados (Self-signed) no están soportados sin acuerdo previo
### 4.2 Cabeceras de solicitud
| Cabecera | Valor / Descripción |
| --------------------- | ------------------------------------------------------------------------- |
| `Content-Type` | `application/json` (por defecto), `text/plain` (cuando se aplica cifrado) |
| `User-Agent` | Identificador propio de ARGOS (ej.: `Argos-kyc-webhook`) |
| `X-Webhook-Encrypted` | `true` / `false` — señal que indica si se ha aplicado cifrado al cuerpo |
### 4.3 Cuerpo de la solicitud (JSON, en modo texto plano)
```json theme={null}
{
"projectId": "",
"submissionId": "",
"userId": "",
"status": "approved | rejected | incomplete",
"timestamp": "",
"webhookParams": { ... }
}
```
La estructura del cuerpo puede variar en función de las opciones del proyecto y del tipo de evento de envío; para la especificación detallada, consulte la documentación de API separada.
***
## 5. Cifrado de datos
### 5.1 Cifrado en tránsito (obligatorio)
* **TLS 1.2 o superior obligatorio** (HTTPS únicamente)
* El envío mediante HTTP en texto plano no está soportado
### 5.2 Cifrado de payload (opcional, activación por proyecto)
Si la organización cliente desea seguridad adicional, puede aplicar un **cifrado adicional sobre TLS** al cuerpo.
| Elemento | Valor |
| -------------------- | ----------------------------------------------------------------- |
| Método de activación | Activar la opción de proyecto `Cifrado de datos` |
| Algoritmo | AES-256 (cifrado de clave simétrica) |
| Derivación de clave | Derivación de clave basada en la API Key del proyecto |
| Cabecera de señal | `X-Webhook-Encrypted: true` |
| Content-Type | `text/plain` (transmisión del texto cifrado codificado en Base64) |
**Procedimiento de descifrado (lado del cliente)**:
1. Verificar la cabecera `X-Webhook-Encrypted`
2. Obtener el cuerpo (decodificación Base64 → texto cifrado)
3. Derivar la clave usando la API Key del proyecto como semilla
4. Descifrado AES-256 → análisis JSON
***
## 6. Autenticación y autorización
### 6.1 Opciones de verificación del remitente por parte del cliente
| Método | Descripción |
| ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **Certificado TLS + verificación del dominio de envío** | El cliente verifica el origen mediante el certificado del dominio de envío de ARGOS |
| **Lista blanca de IP (recomendado)** | Solo se permiten las recepciones del rango de IP fijo del servidor de envío de ARGOS (configuración de firewall del cliente) |
| **Cabecera de modo de cifrado** | Verificación de `X-Webhook-Encrypted: true` y confirmación del origen mediante la capacidad de descifrado |
| **Cabecera de autenticación registrada por el cliente** | Si se acuerda, ARGOS transmite también la cabecera de autenticación especificada por el cliente (ej.: token Bearer) |
Para las organizaciones clientes que requieran una verificación rigurosa del remitente, se recomienda utilizar la combinación de **lista blanca de IP + modo de cifrado de payload**.
### 6.2 Autenticación interna de ARGOS
* Capa de verificación → Capa de convergencia Webhook: llamada interna de AWS (IAM Role + SigV4)
* Capa de convergencia Webhook → Capa de ejecución de envío: llamada de red AWS
***
## 7. Integridad y prevención de alteraciones
| Tramo | Método de garantía de integridad |
| ---------------------- | -------------------------------------------------------------- |
| Canal TLS | Integridad integrada en TLS 1.2+ (AEAD / HMAC) |
| Payload (modo cifrado) | AES-256 + descifrado exitoso = verificación de origen |
| Transmisión TCP | Suma de comprobación TCP + integridad de extremo a extremo TLS |
| Registros de envío | Almacenamiento en tabla de auditoría inmutable (append-only) |
***
## 8. Control de acceso y aislamiento
### 8.1 Aislamiento del destinatario de envío
* La URL Webhook del cliente se **registra y aísla por unidad de proyecto**
* Procedimiento de registro explícito con autenticación de administrador al cambiar la URL
### 8.2 Aislamiento del servidor de envío
* El servidor de envío Webhook de ARGOS opera dentro de AWS **exclusivamente para notificación de resultados**
* No es posible el envío de solicitudes directas a este servidor desde el exterior
* Los destinatarios de envío se limitan a las URL registradas por el cliente
### 8.3 Separación de entornos
* Separación del canal de envío para entornos Live / Test
* Los resultados de prueba solo se envían a la URL registrada del entorno de prueba
***
## 9. Registro y auditoría
### 9.1 Registro por envío unitario
Cada intento de envío de Webhook se registra en la tabla de auditoría con la siguiente información:
| Elemento | Descripción |
| ------------------------- | ------------------------------- |
| Identificador de envío | ID único por unidad |
| Identificador de proyecto | Project ID |
| Hora de envío | Marca de tiempo UTC |
| URL de destino | Endpoint registrado del cliente |
| Código de respuesta HTTP | 200 / 4xx / 5xx |
| Cuerpo de respuesta | Respuesta del cliente |
| Estado | SUCCESS / FAIL / ERROR |
### 9.2 Métricas agregadas diarias
El número de éxitos, fallos y errores por día se agrega en una tabla de métricas separada.
### 9.3 Política de reintentos
| Etapa | Política |
| ------------------- | ----------------------------------------------------------------------------------- |
| Primer intento | Envío inmediato |
| Reintentos | Máximo 3 veces (retroceso exponencial) |
| DLQ / Manual Replay | Los envíos fallidos pueden reenviarse manualmente con una herramienta independiente |
### 9.4 Retención
* El período de retención del registro de auditoría de envíos se define por separado según los requisitos de cumplimiento normativo
***
## 10. Cumplimiento normativo
### 10.1 Certificaciones obtenidas por ARGOS Identity
* **ISO/IEC 27001** — Certificación de norma internacional de gestión de seguridad de la información
### 10.2 Certificaciones de infraestructura AWS (heredadas)
La infraestructura de envío de Webhook (AWS Lambda, EC2, DynamoDB, etc.) hereda las siguientes certificaciones de AWS:
* SOC 1 / SOC 2 / SOC 3
* ISO 27001 / 27017 / 27018
* PCI-DSS Level 1
* HIPAA Eligible
* FedRAMP Moderate
### 10.3 Encargo y recepción de tratamiento de datos
* La información cuyo procesamiento KYC ha sido encargado por el cliente a ARGOS no se utiliza para ningún propósito distinto a la notificación (Webhook) una vez completado el procesamiento.
* La política de limpieza del registro de auditoría de envíos tras la notificación se rige por el acuerdo de tratamiento separado.
***
## Apéndice A. Glosario de términos
| Término | Definición |
| ------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| Webhook | Método de callback asíncrono que notifica resultados mediante HTTPS POST cuando se produce un evento |
| TLS | Transport Layer Security |
| AES-256 | 256-bit Advanced Encryption Standard |
| DLQ | Dead Letter Queue (canal de almacenamiento separado para mensajes fallidos) |
| Retroceso exponencial (Exponential Backoff) | Método que incrementa progresivamente el intervalo entre reintentos |
| Base64 | Codificación segura para texto de datos binarios |
| Lista blanca de IP | Política que restringe la recepción y el envío solo a IP permitidas |
***
## Apéndice B. Guía de integración recomendada
Se recomienda lo siguiente al construir un endpoint receptor de Webhook de ARGOS en la organización cliente:
1. **Uso de endpoint exclusivamente HTTPS** (Let's Encrypt / certificado comercial)
2. **Permitir solo el rango de IP de envío de ARGOS** (configuración de firewall/SG)
3. **Activar el modo `X-Webhook-Encrypted: true`** (activar cifrado de datos en opciones del proyecto)
4. **Responder con 200 OK inmediatamente** tras la recepción y procesar de forma asíncrona (si el retraso supera 3 segundos, puede producirse un reintento)
5. **Gestión de idempotencia (Idempotency)**: garantizar un tratamiento seguro incluso ante recepciones duplicadas del mismo `submissionId`
***
## Apéndice C. Consultas
Para consultas técnicas sobre este documento, póngase en contacto con el canal de soporte técnico y comercial de ARGOS Identity.