Change Notifications

Edit this page

Change notifications deliver events to your application whenever a digital twin or device state changes.

TL;DR: Subscribe to change notifications via WebSocket, Server Sent Events (SSE), or connections. Filter by namespace or RQL expression to receive only the events you care about.

How to receive change notifications

Ditto publishes events through three channels. Each delivers events to authenticated subjects that have the required authorization:

Channel	Format	Use case
WebSocket API	Ditto Protocol messages	Bidirectional communication from browser or backend clients
HTTP SSE	Changed entity JSON (for example, Thing JSON)	Lightweight, read-only streaming in browsers
Connections	Configurable via connectivity	Server-to-server integration with message brokers

Filtering

You can filter events on the Ditto backend before they reach your application. Each API provides its own mechanism for specifying filters. All of them support filtering by namespace and by RQL expression; connections additionally support filtering by placeholder pipeline.

Note: All filters are specified in URL query format, so their values should be URL-encoded. The equal sign (=) and ampersand (&) must be encoded in any RQL filter. The target topics of connections are an exception: there the decoded value is what gets stored, so write the filter expressions unencoded – &, + and % cannot be used in filter values of a target topic at all, an encoded & (%26) does not survive the stored form.

Filter by namespace

Provide a comma-separated list of namespaces to receive events only from Things in those namespaces:

namespaces=org.eclipse.ditto.one,org.eclipse.ditto.two

Filter by RQL expression

For more granular control, use an RQL expression to filter based on:

Thing data – filter on the modified values in the event payload
Ditto Protocol fields – filter on message metadata using placeholders:
- topic:action – filter for lifecycle events (created, deleted)
- resource:path – filter by the affected resource path

Note: The RQL filter applies to the modified data by default. Unchanged data is only considered when it has been enriched via extraFields.

Examples

Only emit events when count changes to a value greater than 42:

filter=gt(attributes/count,42)

Only emit events for Things starting with “myThing” when the “lamp” feature changes:

filter=and(like(thingId,"org.eclipse.ditto:myThing*"),exists(features/lamp))

Only emit events when manufacturer starts with “ACME & Sons” (note the encoded &; not usable in a connection target topic, see the note above):

filter=like(attributes/manufacturer,"ACME %26 Sons*")

Only emit events for Thing creation and deletion:

filter=and(in(topic:action,'created','deleted'),eq(resource:path,'/'))

See the full RQL expression reference for the complete query language.

Filter by placeholder pipeline (connections only)

Connections additionally accept placeholder pipelines in separate, repeatable fn-filter parameters alongside (or instead of) the RQL filter. Each one starts with the placeholder to filter and ends with an fn:filter(...) stage; all given filters must match:

fn-filter=topic:action|fn:filter('eq','modified')

Any placeholder available for the signal can be filtered that way, not only thing data – see Filtering with placeholder functions. This is not available for the WebSocket API or SSE, which only support the namespace and RQL filters.