Enviar eventos de seguridad desde sistemas externos (SIEM, EDR, herramientas de detección) hacia Whalemate.
Registrar incidentes reales fuera de las simulaciones de la plataforma.
Impactar el Human Risk Score de un empleado según la severidad del evento.
Endpoint:
POST {{base_url}}/api/companies/v1/custom-events
Para obtener el host de producción (
base_url), contacta a tu representante de Whalemate o escríbenos a través del chat de soporte.
Autenticación:
La API usa autenticación por API Key mediante el header X-API-KEY.
X-API-KEY: tu_api_key_de_empresa
Puedes generar o consultar tu clave desde Configuración → Integraciones → tarjeta Claves API → Claves Activas. El detalle está en Claves API: cómo generarlas, usarlas y revocarlas.
Headers requeridos:
Header
Valor
Content-Type
application/json
Accept
application/json
X-API-KEY
Tu API Key de empresa
Cuerpo de la solicitud (JSON):
Campo
Tipo
Requerido
Descripción
title
string
✅
Título del evento
victim_email
string
✅
Email del empleado afectado (debe pertenecer a tu organización)
severity
string
✅
low o high
description
string
❌
Descripción opcional del evento
El campo
severitysolo aceptalowyhigh.
Impacto en el Human Risk Score:
Severidad
Cómo se computa
high
Se procesa como compromiso de credenciales
low
Se procesa como un clic en simulación
Ejemplo 1 — Severidad alta:
POST {{base_url}}/api/companies/v1/custom-events
X-API-KEY: tu_api_key_de_empresa
{
"title": "Empleado reportó incidente real",
"victim_email": "[email protected]",
"severity": "high",
"description": "El usuario reportó un email de phishing recibido fuera de campaña"
}
Respuesta exitosa (201 Created):
{
"id": 12345,
"title": "Empleado reportó incidente real",
"description": "El usuario reportó un email de phishing recibido fuera de campaña",
"victim_id": 678,
"severity": "high",
"date_time": "2026-06-09 14:30:00",
"created_at": "2026-06-09 14:30:00"
}
Ejemplo 2 — Severidad baja, sin description:
POST {{base_url}}/api/companies/v1/custom-events
X-API-KEY: tu_api_key_de_empresa
{
"title": "Click manual detectado",
"victim_email": "[email protected]",
"severity": "low"
}
Errores:
Código
Causa
Mensaje
422
El email no pertenece a ningún empleado de tu empresa
"The victim does not belong to your company."
422
Valor de severity inválido
"The severity is not valid. Allowed values: low, high."
401
Falta el header X-API-KEY
"API Key required"
403
La clave no existe o fue revocada
"Invalid API Key"
¿Dónde consigo mi API Key?
En Configuración → Integraciones → tarjeta Claves API → Claves Activas. Ahí se generan, se listan y se revocan.
¿Cómo sé si el evento se registró correctamente?
La API devuelve 201 Created con el objeto del evento creado, incluyendo su id y victim_id. La visualización del evento en el perfil del colaborador dentro de Whalemate estará disponible próximamente.
¿El campo description es obligatorio?
No. Puedes omitirlo. Solo title, victim_email y severity son requeridos.
¿Puedo registrar eventos en lote (batch)?
El endpoint actual procesa un evento por solicitud. El registro en lote estará disponible próximamente. Si es prioritario para tu organización, puedes solicitarlo en roadmap.whalemate.com/roadmap
¿Tienes feedback o quieres solicitar mejoras? Háznos saber en roadmap.whalemate.com/roadmap