> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Events

> An event is a notification of a change - a record of activity in your stack.

Events can represent API calls, state transitions, or changes in your execution environment or infrastructure.

Events power several Prefect features, including flow run logs and [automations](/docs/v3/concepts/automations.md).
In Prefect Cloud, events power [audit logs](/docs/v3/how-to-guides/cloud/manage-users/audit-logs.md).

You can manage events with the [Prefect CLI](https://www.prefect.io/docs/v3/api-ref/cli/event), [Terraform provider](https://registry.terraform.io/providers/PrefectHQ/prefect/latest/docs/resources/automation), or [Prefect API](https://app.prefect.cloud/api/docs#tag/Events).

## Event specification

Events adhere to a structured [specification](https://app.prefect.cloud/api/docs#tag/Events).

![Prefect UI](https://mintcdn.com/prefect-bd373955/dwD6EJObIjtIzwSC/v3/img/ui/event-spec.png?fit=max\&auto=format\&n=dwD6EJObIjtIzwSC\&q=85\&s=7b53476f445e37f4f704a19bb5573817)

| Name | Type | Required? | Description |
| - | - | - | - |
| occurred | String | yes | When the event happened |
| event | String | yes | Name of the event that happened |
| resource | Object | yes | Primary resource this event concerns |
| related | Array | no | List of additional Resources involved in this event |
| payload | Object | no | Open-ended set of data describing what happened |
| id | String | yes | Client-provided identifier of this event |
| follows | String | no | ID of an event that is known to have occurred prior to this one. See [Event ordering](#event-ordering). |

## Event grammar

Events can be named arbitrarily, but are recommended to follow a consistent and informative grammar. An event describes a resource and an action it took—
or that was taken—on that resource.

For example, events emitted automatically by Prefect objects take the following form:

```
prefect.block.write-method.called
prefect-cloud.automation.action.executed
prefect-cloud.user.logged-in
```

See how to [emit and use custom events](/docs/v3/advanced/use-custom-event-grammar.md) to trigger automations.

## Resources

Every event has a primary resource, which describes the object that emitted an event.
Resources are used as quasi-stable identifiers for sources of events, and are represented as dot-delimited strings.

For example:

```
prefect-cloud.automation.5b9c5c3d-6ca0-48d0-8331-79f4b65385b3.action.0
acme.user.kiki.elt_script_1
prefect.flow-run.e3755d32-cec5-42ca-9bcd-af236e308ba6
```

Resources can have additional arbitrary labels which can be used in event aggregation queries.
For example:

```json theme={null}
"resource": {
    "prefect.resource.id": "prefect-cloud.automation.5b9c5c3d-6ca0-48d0-8331-79f4b65385b3",
    "prefect-cloud.action.type": "call-webhook"
    }
```

Events may contain related resources, used to associate the event with other resources.
For example, a primary resource can act on or with another resource.
Here is an example of a related resource:

```json theme={null}
"resource": {
    "prefect.resource.id": "prefect-cloud.automation.5b9c5c3d-6ca0-48d0-8331-79f4b65385b3.action.0",
    "prefect-cloud.action.type": "call-webhook"
  },
"related": [
  {
      "prefect.resource.id": "prefect-cloud.automation.5b9c5c3d-6ca0-48d0-8331-79f4b65385b3",
      "prefect.resource.role": "automation",
      "prefect-cloud.name": "webhook_body_demo",
      "prefect-cloud.posture": "Reactive"
  }
]
```

## Event ordering

Events arrive from many independent sources—your code, workers, and Prefect itself—so
Prefect cannot infer the order of two events from their arrival alone. The `follows` field
declares that order: set it on the later event, referencing the `id` of the earlier one,
to establish that this event is known to have occurred after the other. The system uses
this relationship to disambiguate the ordering of events that occur within a second or
two of each other.

Declare `follows` only between events in the same causal chain, where you know the earlier
event occurred first—for example, a custom event describing how a flow run state change
was handled. [`emit_event`](/docs/v3/api-ref/python/prefect-events-utilities) sets the
relationship when the two events occurred within five minutes of each other.

Ordering matters most to [automation triggers](/docs/v3/concepts/event-triggers.md) whose `after`
and `expect` clauses depend on seeing one event before another. See
[event ordering and `after`](/docs/v3/concepts/event-triggers#event-ordering-and-after) for how
triggers use this relationship, and
[emit events from state change hooks](/docs/v3/how-to-guides/workflows/state-change-hooks.md#emit-events-from-state-change-hooks)
for the most common way to declare it.

## Respond to events

From any event detail page, you can configure an [automation](/docs/v3/concepts/automations.md) to trigger on
the observation of matching events—or a lack of matching events—by clicking the automate button in the overflow menu:

![Automation from event](https://mintcdn.com/prefect-bd373955/ZU4EjeonScNdwFxn/v3/img/ui/automation-from-event.png?fit=max\&auto=format\&n=ZU4EjeonScNdwFxn\&q=85\&s=968f24fb6ffab269039b09d05b3e58aa)

The default trigger configuration fires every time it sees an event with a matching resource identifier.
Advanced configuration is possible through [custom event triggers](/docs/v3/concepts/event-triggers.md).

## Further reading

* [Events reference](/docs/v3/api-ref/events.md): comprehensive catalog of every event emitted by Prefect, Prefect Cloud, and integrations
* [How to create automations](/docs/v3/how-to-guides/automations/creating-automations.md)
* [How to create webhooks](/docs/v3/how-to-guides/cloud/create-a-webhook.md)