Webhook

​

1. Descripción general del documento

​

1.1 Propósito

​

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

​

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

​

3. Flujo de comunicación de red

​

3.1 Flujo completo

​

3.2 Canal de transmisión externo

​

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

​

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)

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

​

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

​

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

​

9.2 Métricas agregadas diarias

​

9.3 Política de reintentos

​

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)

• 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

​

Apéndice B. Guía de integración recomendada

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