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.
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:
- Capa de convergencia de eventos (serverless): decisión del destinatario de envío + composición del cuerpo
- 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
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)
{
"projectId": "<identificador de proyecto>",
"submissionId": "<identificador de envío>",
"userId": "<opcional>",
"status": "approved | rejected | incomplete",
"timestamp": "<hora de envío>",
"webhookParams": { ... }
}
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) |
- Verificar la cabecera
X-Webhook-Encrypted
- Obtener el cuerpo (decodificación Base64 → texto cifrado)
- Derivar la clave usando la API Key del proyecto como semilla
- 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:
- Uso de endpoint exclusivamente HTTPS (Let’s Encrypt / certificado comercial)
- Permitir solo el rango de IP de envío de ARGOS (configuración de firewall/SG)
- Activar el modo
X-Webhook-Encrypted: true (activar cifrado de datos en opciones del proyecto)
- 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)
- 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.
