Notification channels from the system
Purpose
The system informs external clients about what is happening through events (event classes). A client subscribes to events of interest and receives notifications as they occur instead of periodically polling the REST API. The article describes the available channels, the differences between general events and data model events (modelevents), and the approach to maintaining consistent data across several workstations (AWS).
Channels
| Channel | Who subscribes | Which events | Delivery |
|---|---|---|---|
Websocket, User API subscr |
User within their session |
Only |
Into the open websocket connection; subscriptions are deleted when it closes |
Websocket, Token API subscr |
External system by integration channel token |
All classes, including modelevents |
Into the open websocket connection; subscriptions are deleted when it closes |
HTTP webhooks, /rest/v1/service/webhooks |
External system by integration channel token |
All classes except modelevents |
HTTP request to the subscription or integration channel URL; no confirmation or retries |
Kafka |
Configured in the domain (kafka_params, kafka_mustache parameters) |
Classes marked in General event classes; modelevents — only the domain center built-in model (see Kafka and dynamic data model changes) |
Writing to broker topics |
Direct notifications |
User within their session, without subscription |
User state (user_state_changed), script notifications (scriptnotify capability) |
Into the user’s open websocket connection |
Selection recommendations:
-
User interface needing real-time data changes — websocket User API, modelevents events.
-
External system with a persistent connection — websocket Token API: all event classes, delivery order preserved within the connection.
-
HTTP webhooks are not recommended (see Why webhooks are more expensive than websocket); they are used only if the external system cannot hold a websocket connection.
-
Analytics and event bus — Kafka.
Why webhooks are more expensive than websocket
-
A separate HTTP connection is opened for each notification (for https — with a TLS handshake) and closed after the response. Websocket transmits notifications as frames in an already open connection.
-
The request is synchronous: the system waits for the receiver’s response (up to 10 seconds). Notifications to one address are sent sequentially, so a slow or unavailable receiver delays all subsequent notifications to that address and occupies system handler resources.
-
Delivery is not confirmed and not retried: if the receiver is unavailable the notification is lost, and for critical data periodic reconciliation via the REST API is needed. In websocket a connection loss is detected immediately, and the client restores state by re-reading.
-
Data model events (modelevents) are unavailable via webhooks.
Kafka and dynamic data model changes
Events of the dynamic data model modelevents are not sent to Kafka — only to websocket subscribers.
Kafka receives modelevents of the domain center built-in model (for example, /rest/v1/uc/sipusers) and general events per General event classes.
The change stream of dynamic model classes to Kafka is provided by the change history:
-
the class enables the store_changehistory_mode option (
syncorasync): each entity change is recorded in the domain change history class platform/log/HistoryChanges — a single receiver of changes for all domain classes with this option; -
the change history class is placed in storage with the transactionlog storage mode (Kafka; for reading — also ClickHouse): history records go to a Kafka topic. By default the class is created with the
historymode in the default storage, so its placement is changed for the Kafka stream.
A history record contains the time and author of the change, the class, the operation (kind: create, update, replace, delete, clear; rollback — the change was revoked due to a saving failure), the entity identifier and name, changed fields, and the value of the created or deleted entity.
In sync mode the operation with the class completes after writing to history; in async mode the write is performed asynchronously preserving the order of changes.
General subscription rules
-
events— list of events inEventClass.EventTypeformat or"any". -
objects— filter by objects to which the event is bound:"any"or a list. -
In the master domain, callevents and confevents of all domains are available by subscription to the class (
callevents.*) or its event (callevents.invite) with"objects": "any": subscriptions to"any"of these events in the master domain do not receive them, and a subscription with objects is rejected. The stream includes all platform calls: for webhooks it is excessive (see Why webhooks are more expensive than websocket). -
expires— subscription lifetime in seconds. The subscription must be renewed with a repeated request with the sameidbefore expiry.expires= 0 deletes the subscription. For webhooks the term is no more than 86400; the applied value is returned in the response. -
id— subscription identifier; if not set, it is generated and returned in the response. Specified in each notification in thesidfield. -
A new subscription starts receiving events no later than a second after the response.
-
If an event matches several subscriptions of one subscriber, a notification is sent for each of them.
Notification format:
["notify", {"sid": "...", "class": "...", "type": "...", "eventts": 1791975832258, "data": {...}}]
For webhooks the HTTP request body is the object from the second array element.
General events and data model events
Events are divided into two kinds, and subscription to them is arranged differently:
-
General events report what is happening in the system: calls, conferences, scripts, provider and user states (General event classes). Each class has its own set of events. The subscription selects events by their list and by the objects the event relates to (Objects of general events); it does not filter by event content.
-
Data model events (modelevents) report changes to collection records: entity creation, modification, deletion. There is one event —
modelevents.data_changed, and the operation is passed in the notification. The subscription is made to one collection and can select records by content, limit transmitted fields, and operations.
Differences in subscription parameters:
| Parameter | General events | Data model events |
|---|---|---|
|
Events of classes, including the class event mask |
Only |
|
|
One collection: the |
|
Not applied |
|
Subscription permission |
Integration channel subscription right |
IAM read permissions on the collection, data model security policies (Access policies for modelevents) |
General event classes
| Class | Token API (websocket) | Webhooks | Kafka |
|---|---|---|---|
yes |
yes |
yes |
|
yes |
yes |
yes |
|
yes |
yes |
yes |
|
yes |
yes |
yes |
|
yes |
yes |
yes |
|
yes |
yes |
yes |
|
ctievents (master domain) |
yes |
yes |
yes |
Script events ("Generate arbitrary event" component, the class is set by the script) |
yes ("Subscribers" direction) |
yes ("Subscribers" direction) |
yes (KAFKA directions) |
no |
no |
yes |
|
no |
no |
yes |
|
no |
no |
yes |
|
no |
no |
yes |
Events of the registrarevents class are not generated since version 1.8.27; registration states are available via modelevents events of the /rest/v1/uc/sipuser_states collection.
Objects of general events
An event is bound to the objects it relates to and is sent by subscription if at least one of them is specified in objects.
The object is specified by a string:
| Class | Object |
|---|---|
SIP user login or external subscriber number |
|
Conference identifier or room number |
|
Provider account code |
|
SIP user login or user identifier |
|
No object, |
|
Script events |
Login from the event |
The object can also be specified as {"type": "sipuser", "sipuser": "sip1"}; types sipuser, other, conf, provider, user are supported.
Data model events
The class is specified in classpath:
-
dynamic model —
/rest/v1/model/<section>/<Class>; -
static model collections supporting events — for example
/rest/v1/uc/sipusers; -
user section collections
/rest/v1/user/….
The operation is passed in the notification operation field:
-
create— the entity was created, or modified so that it started matching the subscription filter; -
update— the entity was modified, and both the previous and new value match the filter; -
delete— the entity was deleted, or modified so that it stopped matching the filter; -
clear— the collection was cleared; -
reload— change processing for the class was restarted; the collection state must be re-read; -
corrupt— cancels the previous entity change notification: the change was not saved due to a storage failure; the entity must be re-read.
The clear and reload operations concern the whole collection and arrive regardless of the filter.
The corrupt operation occurs only for classes with integrity_mode = sync_fast_notify, where the notification is sent before saving to storage.
If saving then fails, corrupt is sent for the same entity; the subscription filter is applied in the same way as to the original notification, so corrupt is received by the subscribers that received the canceled change. One entity is affected (eid): it must be re-read — the previous value remains in storage. The requested operation was not performed: the initiator receives an error and repeats the operation if necessary.
exargs parameters:
-
filter— an expression as a list, as in the collection REST APIfilterparameter. The event is sent if the previous or new entity value matches the filter. -
mask— list of entity fields transmitted in the notification. -
operations— list of operations to notify about;reload,clear,corruptalways arrive. -
content_mode— notification content: 0 — without the entity, 1 — current entity value (default), 2 — forupdatealso the previous value. -
index— an index condition like["==",["property","<field>"],["const",<value>]]. Acts as a filter "field value equals a constant in the previous or new entity value", with the same reduction of operations to create and delete. Subscriptions with an index are laid out by field value, and when an entity changes the required subscriptions are found by value search without checking each subscription filter. Used instead of a filter when many subscribers are subscribed to one class, each for its own part of records (for example, an executor for records addressed to them). If bothindexandfilterare set, the event is sent when both conditions hold.
Access policies for modelevents
-
Subscription is allowed if the user (for Token API — the user bound to the integration channel, otherwise the channel roles themselves) has IAM read (
GET) permission on the class element or collection. -
For the dynamic model, class security policies are applied to the subscription: the policy filter is combined with the subscription filter via
AND, and the policy mask limits the subscription mask. Policies are not applied to users with the admin role, to classes with disabled security, and to integration channels without a user binding. -
For static model collections only the IAM permission check is applied.
Data consistency across several workstations
All clients subscribed to one class with the same filter receive the same notifications, so their data views coincide if each client builds its state by the rule "subscribe first, then read":
-
Subscribe to collection events with the required filter and accumulate incoming notifications.
-
Read the collection via the REST API with the same filter.
-
Apply the accumulated notifications in arrival order, then apply new ones as they arrive.
-
On a
reloadnotification, and after reconnection, repeat the collection read; oncorrupt— re-read theeidentity. -
Renew the subscription before expiry.
Notification order for one entity is preserved. The version number is not passed in the notification; to control cache integrity you can compare the collection checksum (the hc operation in websocket rest) with the saved one.
Additionally, periodic full re-reading with a large interval is recommended.
Cache loading for the whole collection
For initial loading of a large collection into the cache, instead of page-by-page reading use snapshot reading (the snapshot parameter when reading a collection, dynamic model REST API):
-
snapshot=true— the whole selection as one JSON document: via the HTTP REST API — directly in the response, via websocket — as adownload_urllink to a temporary file that must be downloaded within a minute; -
snapshot=<identifier>— page-by-page reading from a fixed snapshot of identifiers that does not change between pages (for collections of 3000+ records).
Snapshot reading is supported by collections stored in memory (ets, ram, runtime), as well as category with full caching (only snapshot=true).