Listen Live Composite Events

Receive composite events in real time over WebSocket.

Last updated: March 26, 2026

Introduced in v2026.02
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
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
{
  "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",
      "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"
      },
      "location": {
        "latitude": 37.546344,
        "longitude": 126.944322
      },
      "streaming": true,
      "recording": true,
      "status": "active",
      "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,
      "edge_id": "edge_001",
      "edge_status": "active"
    }
  ],
  "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"