Events and Triggers

Events decide when a workflow starts. The events array registers the workflow with Brezel, while the matching event/* element is the actual entry node in the graph.

Webhooks

Use webhook events for explicit user actions, resource-table buttons, detail-view buttons, or calls from another workflow.

{
    "identifier": "createProjectTask",
    "type": "webhook",
    "module": "projects"
}

{
    "name": "createProjectTask",
    "type": "event/webhook",
    "options": {
        "module": "projects",
        "public": false,
        "refresh_prototype": true
    },
    "set": {
        "project": "default:",
        "data": "input:"
    }
}

Use a webhook when the action has a clear command name: create, publish, assign, export, approve, reject, regenerate.

Resource lifecycle events

Use lifecycle events when behavior must happen automatically after or before a resource change.

Event type	Use for
create	Initialize related records after creation.
update	Recalculate derived state after save.
delete	Clean up related records after deletion.
beforeCreate	Validate or enrich data before creation.
beforeSave	Block or adjust a save before persistence.
beforeDelete	Prevent deletion or prepare cleanup.

Keep lifecycle workflows narrow. They may run more often than expected because every save operation can trigger them.

UI events

Use on_click for layout buttons where the layout component emits the event directly.

{
    "identifier": "calculateTaskPreview",
    "type": "on_click",
    "module": "tasks"
}

Use on_change when a field change should set other fields, load options, or validate a small part of the form.

{
    "identifier": "customer",
    "type": "select",
    "options": {
        "references": "customers",
        "events": {
            "on_change": ["setProjectDefaults"]
        }
    }
}

on_change workflows usually receive the current prototype, the original resource, and the selector of the changed field. See Data Flow and UI Integration.

Cron events

Use cron for scheduled maintenance, reminders, status checks, and batch synchronization.

{
    "identifier": "sendTaskReminders",
    "type": "cron",
    "expression": "0 8 * * 1-5"
}

Cron workflows should usually be async: true, log their work, and avoid client-only actions such as action/response, action/set, or action/modal.

Policy and query events

Use policy events to constrain access dynamically.

{
    "identifier": "projectPolicy",
    "type": "policy",
    "module": "projects",
    "roles": ["employee"],
    "operations": ["read", "update"],
    "allow": ["admin", "manager"],
    "roleKey": "slug"
}

Policy workflows typically continue into query/where elements. See Policies and Access.

Use scope or options-style events for reusable query restrictions and dynamic select options. Keep them deterministic and fast because they are often called while the UI is loading.

Choosing a trigger

• Choose webhook for explicit commands.
• Choose on_change or on_click for UI-local interactions.
• Choose lifecycle events for automatic reactions to resource persistence.
• Choose cron for time-based work.
• Choose policy for access constraints.
• Choose action/run from another workflow when orchestration is clearer than exposing a new UI event.