Socket connections can receive events from ThingsDB. Push events do only work when using a socket connection and cannot be used with the HTTP API.

Before events are received you have to subscribe for changes.

The following events may be received by a client:

Event Description
NODE_STATUS (0) The connected node has changed its status.
ON_INIT (1) Initial data for the thing which is added to the watch list.
ON_UPDATE (2) Update on a thing in the watch list.
ON_DELETE (3) A thing in the watch list is removed.
ON_STOP (4) A thing is no longer being watched.
WARNING (5) A warning message.

The number 0-5 represents the package type in a package header.

Subscribe for node status changes

For receiving NODE_STATUS events you need to sent a watch request to the @node scope. At least WATCH permissions for the @node scope are required.

When using a client, this is pretty easy, for example using the Python client:


If you want to write the request to the socket connection yourself, sending the following byte data on your socket connection will have the same result:


(See the “creating a watch request example” on how we got the above bytes code)

Subscribe for thing mutations

If you start to watch a thing, the following events will be pushed in order:

  • ON_INIT, This event will always be pushed on each watch request.
  • ON_UPDATE, You receive an update event for each mutation after the initial ON_INIT event.
  • ON_DELETE or ON_STOP, No more events will be pushed for the thing after this event.

To start watching one or more things, a watch request may be used, but as an alternative it is also possible to use the functions watch() and unwatch. There is no alternative function for watching the node status.