Events

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. In Prefect Cloud, events power audit logs.

import { COMBINED } from "/snippets/resource-management/combined.mdx" import { events } from "/snippets/resource-management/vars.mdx"

Event specification

Events adhere to a structured specification.

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 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:

"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:

"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 sets the relationship when the two events occurred within five minutes of each other.

Ordering matters most to automation triggers whose after and expect clauses depend on seeing one event before another. See event ordering and after for how triggers use this relationship, and 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 to trigger on the observation of matching events—or a lack of matching events—by clicking the automate button in the overflow menu:

The default trigger configuration fires every time it sees an event with a matching resource identifier. Advanced configuration is possible through custom event triggers.

Further reading

• Events reference: comprehensive catalog of every event emitted by Prefect, Prefect Cloud, and integrations
• How to create automations
• How to create webhooks