Listen Live Composite Events

Receive composite events in real time over WebSocket.

Last updated: November 5, 2026

Introduced in v2026.02.1
Changed in v2026.02.2
WebSocket
/api/v1/ws/composite-events

Description

This WebSocket endpoint streams newly created composite events in real time. After the connection is established, the server sends an initial hello text message. Each non-empty JSON message after that follows the same composite event payload returned by Get A Composite Event.

Authentication

Access Token is required in the Authorization header when establishing the WebSocket connection. Use the Bearer scheme: Authorization: Bearer YOUR_ACCESS_TOKEN.

Query Parameters

This WebSocket endpoint does not define query parameters.

Connection Behavior

  • The server sends hello immediately after the WebSocket connection is accepted.
  • The server may send an empty string periodically to keep the connection alive.
  • Ignore empty keep-alive messages and parse non-empty JSON messages as composite event payloads.

Event Message Format

Messages received after the initial hello follow the structure below:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
{
  "id": "composite_evt_123",
  "group_key": "edge-01:normal_speech_female",
  "rule": {
    "id": "rule_001",
    "name": "Repeated Speech Cluster",
    "description": "Groups repeated speech events within the same window",
    "window_seconds": 30,
    "min_events": 3,
    "enabled": true,
    "group_by": "label_id",
    "include_label_ids": [
      "normal_speech_female"
    ],
    "include_mic_ids": [
      "mic_001",
      "mic_002"
    ]
  },
  "events": [
    {
      "id": "evt_001",
      "confidence": 0.93,
      "confidence_threshold": 0.5,
      "sound_level": 71.2,
      "sound_level_threshold": 65,
      "description": "Repeated speech detected near entrance",
      "audio_file": {
        "file_path": "/audio/events/evt_001.wav"
      },
      "is_read": false,
      "read_at": null,
      "created_at": "2026-03-26T09:00:00Z",
      "updated_at": "2026-03-26T09:00:05Z",
      "label_id": "normal_speech_female",
      "mic_id": "mic_001",
      "label": {
        "id": "normal_speech_female",
        "name": {
          "ko": "female speech",
          "en": "normal speech female"
        },
        "active": true
      },
      "microphone": {
        "id": "mic_001",
        "name": "Entrance Mic",
        "host": "172.16.10.21",
        "subnet_mask": "255.255.255.0",
        "mac_address": "00:11:22:33:44:55",
        "microphone_type": "PDM_715IP",
        "channel": {
          "scheme": "rtsp",
          "port": 554,
          "path": "/stream",
          "username": null,
          "password": null
        },
        "console": {
          "scheme": "http",
          "port": 80,
          "path": "/",
          "username": "admin",
          "password": "password"
        },
        "streaming": true,
        "recording": true,
        "edge_id": "edge_001",
        "location": {
          "latitude": 37.546344,
          "longitude": 126.944322
        },
        "status": "active",
        "thresholds": {},
        "created_at": "2026-03-01T00:00:00Z",
        "updated_at": "2026-03-26T09:00:05Z",
        "deleted_at": null,
        "reported_at": "2026-03-26T09:00:05Z",
        "connected": true
      }
    }
  ],
  "mics": [
    {
      "id": "mic_001",
      "name": "Entrance Mic",
      "host": "172.16.10.21",
      "edge_id": "edge_001",
      "status": "active",
      "thresholds": {
        "breathing_heavily": {
          "sound_level_ge": 65,
          "confidence_ge": 0.8
        }
      },
      "location": {
        "latitude": 37.546344,
        "longitude": 126.944322
      },
      "created_at": "2026-03-01T00:00:00Z",
      "updated_at": "2026-03-26T09:00:05Z"
    }
  ],
  "labels": [
    {
      "id": "normal_speech_female",
      "name": {
        "ko": "female speech",
        "en": "normal speech female"
      },
      "active": true
    }
  ],
  "started_at": "2026-03-26T08:59:45Z"
}

Example Connection

npx wscat -c "ws://{{EDGE_IP}}:8100/api/v1/ws/composite-events" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"