This article provides a concise overview of how to integrate with the Dersalis Cloud API, enabling technical teams to connect internal systems to real-time and historical incident data.
For the full technical documentation, a request channel is available at the end.
1. Overview
The Cloud API allows partners to:
Retrieve historical incidents
Receive real-time events via Webhook
Reconstruct the complete lifecycle of each incident
Integrate data into dashboards, ERPs, SOC tools and internal systems
Two mechanisms are available:
1) Endpoint query (GET /incident)
2) Real-time notifications via Webhook
2. Core Auxiliary Types
export type UnixTime = number; export interface TimeOfDay { hour: number; minute: number; } export interface TimeWindow { startTime: TimeOfDay; endTime: TimeOfDay; active: boolean; timeZone: string; } export type NotificationChannel = "whatsapp" | "sms" | "teams" | "slack";3. Monitoring Object (summary)
export interface Monitoring { id: string; name: string; monitoredIndividualIdList: string[]; monitoredIndividualGroupIdList: string[]; timeWindow: TimeWindow; riskSettings: any[]; notificationSettings: any[]; active: boolean; }4. Incident Object (summary)
export interface Incident { id: string; monitoring: Monitoring; monitoredIndividual: { id: string; registrationCode: string; }; state: "open" | "finished" | "closed"; openTimestamp: UnixTime; finishTimestamp: UnixTime; closeTimestamp: UnixTime; severityLevel: number; log: IncidentLifeCycleEvent[]; location?: any; }5. Lifecycle Events (summary)
export type IncidentLifeCycleEvent = | { type: "create"; timestamp: UnixTime } | { type: "finish"; timestamp: UnixTime } | { type: "close"; timestamp: UnixTime } | { type: "severity-level-change"; timestamp: UnixTime; newSeverityLevel: number } | { type: "notification-report"; timestamp: UnixTime; channels: NotificationChannel[] } | { type: "handling-report"; timestamp: UnixTime; handlingOperatorId: string } | { type: "sample-data-ref"; timestamp: UnixTime; sampleDataId: string };6. Querying Incidents – GET /incident
GET /incident?start=1711900000000&end=1712000000000 Authorization: Bearer <token>
Returns:
full incidents
logs
severity
timestamps
Ideal for synchronization and audits.
7. Webhook – Real-Time Events
Example payload:
{ "eventType": "create", "timestamp": 1711920032000, "incidentId": "abc-123", "data": { } }Supported event types:
create
finish
close
severity-level-change
notification-report
handling-report
sample-data-ref
8. Operational Recommendations
Use Webhook for real-time processing
Use
/incidentfor resilience and cross-checkingEnsure idempotent processing
Store events using (
incidentId,timestamp) as a unique key
9. Full Documentation Request
If your team requires:
full type definitions
advanced structures
complete payloads
detailed behavior and lifecycle rules
You can request the full technical documentation from the Dersalis team.