> For the complete documentation index, see [llms.txt](https://docs.heisenware.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.heisenware.com/concepts/backend-events.md).

# Backend events

How an App listens to machines, brokers and timers: event functions, event outputs and subscriptions.

Some things report by themselves: an MQTT message arrives, an OPC UA node changes, a timer ticks. An **event function** listens for them. It is called once and then delivers a value every time something happens, until it is released. Most event functions start with `on`: `onMessage`, `onChange`, `onTick`.

## Event outputs

An event function takes a **handler** as an input: the piece that receives the events. On the Flowboard, everything the handler receives appears as **event outputs** below the executor's return, one for each value the event delivers.

* The **return** only answers the call. For an event function it says that listening has begun.
* The **event outputs** carry the data. Each one works like any output: it shows the last value, takes wires and widget links, and carries its own [extensions](https://docs.heisenware.com/concepts/extensions-branching-and-errors.md).

<figure><img src="https://3495989837-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FE5Ketpww1s7TauSAJrJ8%2Fuploads%2Fgit-blob-b9b2e184ca6f74c5286fa954f310196aa82518be%2Fconcept-event-outputs.png?alt=media" alt="An executor calling onTick: its handler input, the return holding only true, and below it the three event outputs the handler&#x27;s documentation names" width="563"><figcaption><p>The handler's values arrive on event outputs, not on the return</p></figcaption></figure>

So wire from the event output, not from the return. To run another executor on every event, drop the event output onto its trigger.

Where a function's documentation names what its events deliver, the event outputs carry those names. Otherwise right-click the handler and choose how many values to show.

{% hint style="info" %}
A **callback** is the one-time relative of an event: a handler the function calls once, for example when a long operation has finished. Its value arrives on an event output in the same way.
{% endhint %}

## Subscriptions

Triggering an event executor declares a **subscription**: the App's standing wish to receive those events, with these inputs, from this instance.

* **Start it with the App.** Give the executor the trigger **App Start**. A deployed App listens only to what its logic declares.
* **Triggering again is harmless.** The same inputs change nothing. Other inputs or another address move the subscription to the new target.
* **It heals by itself.** When the agent or the instance goes away and comes back, the subscription continues without the executor running again.
* **It pauses with the App.** A stopped App listens to nothing. Start a **Test** before you check whether events arrive.
* **It ends with its scope.** A subscription a user's click declared ends when that user's last connection closes. One declared at App start has no end of its own: stopping the App pauses it, the next start declares it again.

The executor shows the state of its subscription: listening, waiting (for example for an agent that is offline), paused, ended or failed, with the reason. **Stop listening** ends it until the next trigger.

## Who receives an event

An event arrives in the [scope](https://docs.heisenware.com/concepts/scopes.md) its subscription was declared in:

* Declared at App start, it is the App's: what it triggers runs once for everyone, and every user sees the result.
* Declared by a user's action, it is that user's: only that user's App reacts.

## Many devices, one executor

Set the instance in the [address](https://docs.heisenware.com/concepts/executors-and-instances.md#addresses-where-a-call-goes) to `*`, and one event executor listens to every instance of the class, including those created later. Its first event output then names the instance that sent the event, and the event's own values follow. Twenty identical machines need one executor, not twenty.

## Events and polling

Prefer an event where the source offers one. An event costs nothing while nothing happens and arrives at once. [Polling](https://docs.heisenware.com/concepts/triggers-and-wires.md#polling) is for sources that only answer when asked.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.heisenware.com/concepts/backend-events.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
