Integration: Custom Events API - Whalemate Docs

Technical reference for integrating external systems with the Whalemate Custom Events API. It allows recording real security events associated with employees, which directly impact their Human Risk Score.

What is it for?

Send security events from external systems (SIEM, EDR, detection tools) to Whalemate.
Record real incidents outside of the platform's simulations.
Impact an employee's Human Risk Score based on the event's severity.

How is it implemented?

Endpoint:

POST {{base_url}}/api/companies/v1/custom-events

To get the production host (base_url), contact your Whalemate representative or write to us through the support chat.

Authentication:

The API uses API Key authentication via the X-API-KEY header.

X-API-KEY: tu_api_key_de_empresa

You can generate or check your API Key from Configuración → General → API Keys → Claves Activas.

Required headers:

Header	Value
`Content-Type`	`application/json`
`Accept`	`application/json`
`X-API-KEY`	Your company API Key

Request body (JSON):

Field	Type	Required	Description
`title`	string	✅	Event title
`victim_email`	string	✅	Email of the affected employee (must belong to your organization)
`severity`	string	✅	`low` or `high`
`description`	string	❌	Optional description of the event

The