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

# Events

## What are Events?

An **event** is a signal that something has happened. Instead of one flow calling another directly, a flow simply announces that an event occurred, and any flow that cares about that event responds on its own. This keeps your integrations loosely coupled: the flow that produces the signal doesn't need to know who is listening, and you can add or remove listeners without changing the flow that raises the event.

A typical event-driven pattern in Astera looks like this:

1. An event happens either because a flow deliberately **raises** it, or because a platform operation (such as creating a database table) raises it automatically.
2. The event carries a small package of data called its **payload** (for example, an order ID and an amount).
3. One or more **subscriber** flows that are listening for that event are triggered, receive the payload, and process it.

<figure><img src="/files/dEm2wiRRtOAXBjlKTkWh" alt=""><figcaption><p>01-events-journey</p></figcaption></figure>

### Why Use Events? <a href="#why-use-events" id="why-use-events"></a>

Events suit scenarios where one action should fan out to several independent reactions:

* When an order is processed, notify billing, update a report, and archive the record, each in its own flow.
* When a database table is created or truncated, log the change for auditing.
* Let different teams add their own subscriber flows to an existing event without touching the original flow.

### Key Concepts <a href="#key-concepts" id="key-concepts"></a>

| Term            | Meaning                                                                                                   |
| --------------- | --------------------------------------------------------------------------------------------------------- |
| **Event type**  | An event's definition — its name and payload structure.                                                   |
| **Payload**     | The set of fields an event carries.                                                                       |
| **Raise**       | To announce that an event has occurred, along with its payload.                                           |
| **Subscribe**   | To listen for an event type so a flow runs when it is raised.                                             |
| **Match value** | An optional per-field filter so a subscriber reacts only to events whose payload matches specific values. |

### Two Kinds of Events <a href="#two-kinds-of-events" id="two-kinds-of-events"></a>

* **Custom Events**: Events you define yourself and raise explicitly from a flow. See [Custom Events](/project-management-and-scheduling/events/custom-events.md).
* **System Events**: Events the platform provides and raises automatically (a table created or truncated, a job finished, a file arrived). You only subscribe to them. See [System Events](/project-management-and-scheduling/events/system-events.md).

Both are consumed the same way — by subscribing.

### The Building Blocks

Working with events involves up to three objects, in the toolbox's **Events** category. Each lives in its own file:

* **Custom Event**: Defines a custom event type and its payload, inside a shared action so it can be reused across the project. *(Not needed for system events.)*
* **Raise Event**: A **destination** object that raises a custom event, mapping incoming data into the payload. *(Not used for system events.)*
* **Event Subscription**: A **source** object that begins a **subscriber** flow, exposing the event payload for the rest of the flow to act on. Used for both kinds of events.

### How Events Are Delivered

The server delivers events, starting each matching subscriber flow as a job and passing it the payload. A subscriber responds in one of two ways:

* **Local**: A subscriber in the same project as the flow raising the event. When that project runs, it carries its subscribers with it, so they respond **without being published** — ideal while building and testing.
* **Published**: A subscriber deployed to the server. It runs automatically whenever a matching event is raised by **any** source, independently of any run.

Publishing is **not** required for a subscriber to respond within its own project's run. Publish it when it should react to events from other flows and keep listening continuously.


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://documentation.astera.com/project-management-and-scheduling/events.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.