Object Record Events

This page documents the WebSocket endpoint used to receive real-time Object Record change events in Catalyst.

The endpoint broadcasts Object Record-related events so that connected clients can reflect changes without polling or refreshing the page. It is intended for real-time UI updates and event-driven integrations that need to track record creation, value changes, ownership changes, assignment changes, document generation, and deletion.

WARNING

This section documents technical and service-level WebSocket APIs. It should be used as implementation reference material and not treated as end-user documentation.

Endpoint overview

This page covers the following endpoint:

• GET /ws/events/object-records/

GET /ws/events/object-records/

Subscribes the client to a stream of Object Record change events.

The endpoint broadcasts updates for up to 1,000 Object Records every 5 seconds.

Permissions

Requires authentication.

Authentication is based on the uuid query string parameter used when establishing the WebSocket connection.

Request

Upgrade request example

Request Method: GET
Connection: Upgrade
Upgrade: websocket

Query parameters

Optional filters can be passed in the WebSocket connection query string, alongside the uuid authentication parameter.

Parameter	Type	Notes
object_class_ids	comma-separated int list	Optional. Limits delivered notifications to events where object_class_id matches one of the provided IDs.
field_ids	comma-separated int list	Optional. Limits delivered object_record_value_changed notifications to events that include at least one matching Object Class Field ID. Other event types are not restricted by this parameter.

Examples:

GET /ws/events/object-records/?uuid=<uuid>&object_class_ids=1,2
GET /ws/events/object-records/?uuid=<uuid>&field_ids=10,11
GET /ws/events/object-records/?uuid=<uuid>&object_class_ids=1,2&field_ids=10,11

Empty parameters are treated as no filter. Invalid comma-separated values are silently ignored. A filter is active only when at least one valid integer value remains after parsing.

Filtering behaviour

When object_class_ids is provided, the server delivers only notifications where object_class_id matches one of the provided values. Notifications for other Object Classes are dropped server-side.

When field_ids is provided, it applies only to object_record_value_changed notifications:

• a value-changed notification is delivered only when at least one changed field ID matches the provided field_ids
• the forwarded field_ids list contains only the matched subset
• other event types, such as object_record_created and object_record_deleted, are not restricted by this filter

When both object_class_ids and field_ids are provided, both filters apply. A notification must pass the Object Class filter and, for object_record_value_changed notifications, the field filter to be delivered.

Connections without object_class_ids or field_ids receive all events, preserving the previous behaviour.

Response

After the connection is established, the server sends a list of Object Record change events.

Each list item contains the following fields:

Key	Type	Notes
object_record_id	int	Object Record identifier
object_class_id	int	Related Object Class identifier
event	string	Object Record event type
field_ids	array[int]	Included on object_record_value_changed events. Contains the changed Object Class Field IDs. When field_ids filtering is active, contains only the matched subset.
timestamp	datetime	Time the event was created

For object_record_value_changed, a single backend event with multiple changed fields produces one WebSocket message with a field_ids list. The message does not use a single field_id integer.

Available events

The following event values are supported:

• object_record_created
• object_record_value_changed
• object_record_owner_initialized
• object_record_owner_added
• object_record_owner_removed
• object_record_assignee_added
• object_record_assignee_removed
• object_record_deleted
• object_record_document_generated

Success

• WebSocket upgrade status: 101 Switching Protocols

Example payload

[
  {
    "object_record_id": 1,
    "object_class_id": 1,
    "event": "object_record_owner_initialized",
    "timestamp": "2025-01-16T11:07:57.954470+00:00"
  },
  {
    "object_record_id": 1,
    "object_class_id": 1,
    "event": "object_record_created",
    "timestamp": "2025-01-16T11:07:57.934931+00:00"
  },
  {
    "object_record_id": 1,
    "object_class_id": 1,
    "event": "object_record_value_changed",
    "field_ids": [10, 11],
    "timestamp": "2025-01-16T11:08:07.444085+00:00"
  }
]

Ordering and delivery

Sorting cannot be controlled by the client.

By default, events are delivered in creation order. Where results are chunked, events are ordered in ascending order by event timestamp.

Errors

Error	Response code / close status	Message
Incorrect WebSocket URL path	Close: 1000 Normal Closure	"type": "error", "error_code": "ERR_INCORRECT_URL", "detail":"Incorrect WebSocket URL."
Invalid UUID	Close: 1000 Normal Closure	"type": "error", "error_code": "ERR_INVALID_UUID", "detail":"A valid UUID is required."
Sending messages to this WebSocket is not supported	Close: 1000 Normal Closure	"type": "error", "error_code": "RECEIVE_NOT_SUPPORTED", "detail": "This WebSocket connection does not support receiving messages."
Rate limit exceeded	Close: 1000 Normal Closure	"type": "error", "error_code": "ERR_RATE_LIMIT_EXCEEDED", "detail":"The rate limit for requests has been exceeded. Please wait before trying again."
Error during the handshake	500 Internal Server Error

Notes

WebSocket standard close/error definitions are described in RFC 6455.