Task Events

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

The endpoint broadcasts Task-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 Task creation, updates, ownership changes, assignment changes, 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/tasks/

GET /ws/events/tasks/

Subscribes the client to a stream of Task change events.

The endpoint broadcasts updates for up to 1,000 tasks 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

Response

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

Each list item contains the following fields:

Key	Type	Notes
task_id	int	Task identifier
object_class_id	int	Related Object Class identifier
event	string	Task event type
timestamp	datetime	Time the event was created

Available events

The following event values are supported:

• task_created
• task_value_changed
• task_status_changed
• task_owner_added
• task_owner_removed
• task_assignee_added
• task_assignee_removed
• task_deleted

Success

• WebSocket upgrade status: 101 Switching Protocols

Example payload

[
  {
    "task_id": 1,
    "object_class_id": 1,
    "event": "task_created",
    "timestamp": "2025-01-16T11:07:57.954470+00:00"
  },
  {
    "task_id": 1,
    "object_class_id": 1,
    "event": "task_status_changed",
    "timestamp": "2025-01-16T11:07:57.934931+00:00"
  },
  {
    "task_id": 1,
    "object_class_id": 1,
    "event": "task_deleted",
    "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.