Event-driven triggers

Event-driven triggers let workflows react to events elsewhere in Kibana. The following trigger families are available:

• workflows.failed: Fires when another workflow's execution fails.
• Cases triggers: Fire when cases change (created, updated, status changed, attachments added, comments added).
• Entity store triggers: Fire when an entity's asset criticality or risk score changes in the entity store.
• Alert lifecycle triggers in Kibana Universal Alerting: Fire when a user takes a triage action on an alert, such as resolving, assigning, acknowledging, or snoozing it.
• Rule lifecycle triggers in Kibana Universal Alerting: Fire when someone creates, updates, deletes, enables, or disables a rule.
• Elastic Agent Builder triggers: Fire when a conversation attachment is added, updated, or deleted, or when conversation metadata changes. ai.conversation.updated also fires for other conversation changes, but only for conversation templates that have it turned on.

The privileges used for each event-driven run depend on whether the workflow has an assigned service account:

• No service account assigned (default): The run uses the privileges of the user whose action produced the event. For workflows.failed, it uses the same privileges as the failed workflow.
• Service account assigned: The run uses the privileges of that account.

For details, refer to Workflow authorization.

Fires when any workflow execution reaches the failed terminal state. Use this trigger to build handler workflows that react to failures in your production workflows, for example by paging on-call, opening a case, or logging to a dedicated index for observability.

Schema convention. In each schema table on this page, the Location column indicates where each parameter sits in the YAML:

• top level: Alongside type and name, at the top of the step or trigger definition.
• `with`: Inside the step's with: block.
• `on`: Inside the trigger's on: block.

triggers:
  - type: workflows.failed
		

Use on.condition to narrow which failed executions trigger the handler. The value is a KQL predicate evaluated against the event payload.

Fire only on failures from a specific workflow:

triggers:
  - type: workflows.failed
    on:
      condition: "event.workflow.name : 'ops--rollback-deployment'"
		

Ignore failures that came from another error handler:

triggers:
  - type: workflows.failed
    on:
      condition: "event.workflow.isErrorHandler : false"
		

Combine conditions with KQL's and to filter on multiple fields:

triggers:
  - type: workflows.failed
    on:
      condition: "event.workflow.isErrorHandler : false and event.workflow.spaceId : 'production'"
		

When a failed workflow triggers your handler, the handler runs with an event context that describes the failure. The payload has four groups: workflow, execution, error, and the top-level timestamp and spaceId.

Reference these fields with Liquid templating inside the handler:

- name: log_failure
  type: console
  with:
    message: |
      Workflow {{ event.workflow.name }} (id: {{ event.workflow.id }}) failed
      at step {{ event.error.stepName }}: {{ event.error.message }}
		

name: handle-critical-workflow-failures
description: Page on-call and open a case whenever a critical workflow fails.
enabled: true

triggers:
  - type: workflows.failed

steps:
  - name: skip_if_handler
    type: if
    condition: "event.workflow.isErrorHandler : true"
    steps:
      - name: no_op
        type: console
        with:
          message: "Skipping: the failure came from another error handler."

  - name: page_oncall
    if: "not event.workflow.isErrorHandler"
    type: pagerduty.triggerIncident
    connector-id: "platform-pagerduty"
    with:
      dedup_key: "{{ event.workflow.id }}-{{ event.execution.id }}"
      summary: "Workflow {{ event.workflow.name }} failed"
      severity: "critical"
      details:
        failed_step: "{{ event.error.stepName }}"
        error: "{{ event.error.message }}"
        workflow_id: "{{ event.workflow.id }}"
        execution_id: "{{ event.execution.id }}"

  - name: open_case
    if: "not event.workflow.isErrorHandler"
    type: cases.createCase
    with:
      title: "[Auto] Workflow failure: {{ event.workflow.name }}"
      description: |
        Step `{{ event.error.stepName }}` failed.

        Error: `{{ event.error.message }}`
      severity: "high"
      tags: ["workflow-failure", "auto-triage"]
		

Cases triggers fire when cases change. Use them to react to case lifecycle events without polling the Cases API.

Shared payload. Every cases trigger event includes:

• event.caseId — The case ID, the alphanumeric identifier that is unique to each case.
• event.owner — The solution that owns the case. It can be securitySolution for Elastic Security cases, observability for Observability cases, or cases for Stack cases.

Use event.owner in on.condition to filter by solution. For example, a workflow that only fires for Elastic Security cases:

triggers:
  - type: cases.caseCreated
    on:
      condition: 'event.owner: "securitySolution"'
		

Individual trigger sections below document any additional payload fields specific to that event.

Fires when a case is created.

Fire only for Elastic Security cases:

triggers:
  - type: cases.caseCreated
    on:
      condition: 'event.owner: "securitySolution"'
		

Fires when a case is updated. The event.updatedFields array lists which fields changed.

This trigger also fires when a case's status changes; the dedicated cases.caseStatusUpdated trigger fires alongside it and carries the previous status for easier filtering. For bulk updates, cases.caseUpdated fires once per case.

Fire when a Elastic Security case's title changes:

triggers:
  - type: cases.caseUpdated
    on:
      condition: 'event.owner: "securitySolution" and event.updatedFields: "title"'
		

Fires when a case's status changes.

Fire when a Elastic Security case is closed:

triggers:
  - type: cases.caseStatusUpdated
    on:
      condition: 'event.owner: "securitySolution" and event.status: "closed"'
		

Fires when attachments are added to a case. If attachments of multiple types are added in one operation (for example, three alerts and two comments), the trigger fires once per type, with one event for each type.

Adding a comment fires both this trigger (with event.attachmentType: "comment") and the dedicated cases.commentsAdded trigger. Both exist because users don't always think of comments as attachments.

Fire only for Elastic Security cases:

triggers:
  - type: cases.attachmentsAdded
    on:
      condition: 'event.owner: "securitySolution"'
		

Fire only when a comment-type attachment is added:

triggers:
  - type: cases.attachmentsAdded
    on:
      condition: 'event.attachmentType: "comment"'
		

Fires when comments are added to a case.

Fire only for Elastic Security cases:

triggers:
  - type: cases.commentsAdded
    on:
      condition: 'event.owner: "securitySolution"'
		

Entity store triggers fire when an entity in the entity store changes. Use them to react to changes in an entity's asset criticality or risk score without polling.

Fires when an entity's asset criticality level is assigned or cleared.

Fire when an entity is assigned high or extreme impact:

triggers:
  - type: entityStore.entityAssetCriticalityUpdated
    on:
      condition: 'event.criticalityLevel: "high_impact" OR event.criticalityLevel: "extreme_impact"'
		

Fire only when a host entity's criticality changes:

triggers:
  - type: entityStore.entityAssetCriticalityUpdated
    on:
      condition: 'event.entityType: "host"'
		

Fire when criticality is removed from an entity:

triggers:
  - type: entityStore.entityAssetCriticalityUpdated
    on:
      condition: 'NOT event.criticalityLevel: *'
		

Fires when an entity's risk score changes.

Fire when a risk score increases by 25 or more:

triggers:
  - type: entityStore.entityRiskScoreChanged
    on:
      condition: 'event.direction: "increase" AND event.delta >= 25'
		

Fire when a risk score decreases:

triggers:
  - type: entityStore.entityRiskScoreChanged
    on:
      condition: 'event.direction: "decrease"'
		

Fire when a risk score crosses a high-risk threshold:

triggers:
  - type: entityStore.entityRiskScoreChanged
    on:
      condition: 'event.score >= 70'
		

Alert lifecycle triggers run a workflow when a user acts on an alert in Kibana Universal Alerting, either in the UI or through the API. They don't fire when an alert becomes active or recovers based on rule evaluations. To run a workflow when an alert's status changes automatically, use an action policy instead. For a comparison, refer to When to use action policies or lifecycle triggers.

Each trigger fires exactly once per event. To subscribe a workflow, add the trigger ID to its triggers block, as with other event-driven triggers.

All lifecycle triggers include these common fields in the event payload.

Reference these fields with Liquid templating in workflow steps:

- name: log
  type: console
  with:
    message: |
      Alert {{ event.alertId }} from rule {{ event.ruleId }} changed state.
		

Use these fields to write workflow conditions that scope the automation to specific rules or alerts. For example, use event.ruleId: "my-rule-id" to scope the workflow to alerts from a specific rule.

Rule lifecycle triggers run a workflow when someone creates, updates, deletes, enables, or disables a rule in Kibana Universal Alerting. Use them to automate responses to rule management actions, for example, auditing rule changes, syncing rule inventory with an external CMDB, or notifying a team channel when a new rule is added to a space.

Rule lifecycle triggers fire independently of alerts.

For bulk operations (bulk enable, bulk disable, bulk delete), one trigger event is emitted for each affected rule.

triggers:
  - type: alerting.ruleCreated
  - type: alerting.ruleUpdated
  - type: alerting.ruleDeleted
  - type: alerting.ruleEnabled
  - type: alerting.ruleDisabled
		

All rule lifecycle triggers share the same minimal payload.

Reference these fields with Liquid templating in workflow steps:

- name: log_rule_event
  type: console
  with:
    message: |
      Rule {{ event.rule.ruleId }} changed in space {{ event.rule.spaceId }}.
		

Use on.condition to scope the trigger to a specific rule or space:

triggers:
  - type: alerting.ruleCreated
    on:
      condition: 'event.rule.spaceId: "production"'
		

name: audit-rule-changes
description: Log rule lifecycle events across all spaces.
enabled: true

triggers:
  - type: alerting.ruleCreated
  - type: alerting.ruleUpdated
  - type: alerting.ruleDeleted
  - type: alerting.ruleEnabled
  - type: alerting.ruleDisabled

steps:
  - name: log_change
    type: console
    with:
      message: |
        Rule {{ event.rule.ruleId }} in space {{ event.rule.spaceId }} — trigger: {{ trigger.type }}
		

Elastic Agent Builder triggers run a workflow when a conversation changes. Use them to react to attachment changes, metadata updates, and, for supported conversation templates, new messages and other conversation changes without polling the Elastic Agent Builder APIs.

The attachment and metadata triggers are available wherever Elastic Agent Builder is available. They aren't available in Observability Logs Essentials projects or in Security Analytics Essentials projects, where Elastic Agent Builder is turned off.

ai.conversation.updated has an additional requirement: it fires only for conversation templates that a Kibana feature has turned it on for. Refer to the trigger's section for details.

Attachment triggers fire after the change is saved to the conversation.

An attachment trigger doesn't fire in these cases:

• Hidden attachments: Hidden attachments are internal conversation data, so adding, updating, or deleting one doesn't fire a trigger.
• Changes other than content: Edits to the description, the hidden setting, or the read-only setting don't fire ai.attachmentUpdated. Renaming an attachment or changing its origin doesn't fire a trigger.
• Identical content: The new content is identical to the current version.
• Restores: Restoring a soft-deleted attachment doesn't fire a trigger.
• Permanently deleting a soft-deleted attachment: The soft delete already fired ai.attachmentDeleted.

Every attachment trigger event includes these fields:

event.source is one of these values:

To skip attachment changes caused by workflows, pick the control that matches your goal:

triggers:
  - type: ai.attachmentAdded
    on:
      condition: 'not event.source: "workflow"'
		

Fires when an attachment is added to a conversation. event.currentVersion is 1.

In addition to the shared attachment fields:

Fire when an agent run attaches a dashboard:

triggers:
  - type: ai.attachmentAdded
    on:
      condition: 'event.attachmentType: "platform.dashboard.dashboard_state" and event.source: "execution"'
		

Fires when a new content version of an attachment is stored. event.currentVersion is greater than event.previousVersion. Edits that don't change attachment content don't fire this trigger.

In addition to the shared attachment fields:

Fire when a user edits attachment content through chat or the attachment HTTP API:

triggers:
  - type: ai.attachmentUpdated
    on:
      condition: 'event.source: "http_api" or event.source: "chat_input"'
		

Fires when an attachment is soft-deleted or permanently deleted while it's still active. A soft-deleted attachment can be restored.

In addition to the shared attachment fields:

Fire only when an attachment is permanently deleted:

triggers:
  - type: ai.attachmentDeleted
    on:
      condition: 'event.hardDelete: true'
		

Fires after a successful metadata update changes at least one stored field. Only conversations that use a template have metadata, so this trigger fires only for those conversations. The available templates are investigation and escalation.

This trigger doesn't fire when:

• The update changes nothing.
• Creating a conversation or applying a template sets metadata.

The payload has no event.source field. To skip changes made by workflows, use on.workflowEvents.

Fire when a decision is recorded:

triggers:
  - type: ai.conversation.metadataUpdated
    on:
      condition: 'event.changedFields: "decision"'
		

Fires after a successful conversation write that changes the conversation: new events, attachments, metadata, the title, the template, or access.

This trigger doesn't fire for:

• A write that changes nothing.
• Changes that only affect hidden attachments.
• Deleting a conversation, marking it as read, pinning it, or saving feedback on an agent response.

The payload describes the write and doesn't include field values. Read the conversation when you need the values.

Keep these behaviors in mind when you write an on.condition:

• Array fields: An array field matches when any element matches. For example, event.eventTypes: "user_message" matches a write that added a user message among other events.
• Missing fields: A wildcard on a missing field doesn't match, so event.executionId: * matches only writes that saved an agent run.
• New conversations: A write that creates a conversation reports created plus everything set at creation, including template defaults. Add not event.changeKinds: "created" when a condition should match only later changes.
• Activity events: Creating a conversation, applying a template, and changing the title, metadata, or access also add activity events to the conversation: conversation_created, title_updated, metadata_updated, visibility_updated, participants_added, or participants_removed. These writes report events in event.changeKinds too. To react only to new messages, filter on event.eventTypes instead of event.changeKinds: "events".
• Hidden attachments: Events for hidden attachments are left out of event.eventTypes. Attachments that are hidden both before and after the write are left out of event.attachmentTypes and event.attachmentIds. A write that hides a visible attachment or reveals a hidden one is still reported in those fields.

A single conversation can produce a burst of writes, for example while an agent runs. To coalesce them into one run at a time per conversation, set a concurrency key that includes the workflow ID and event.conversationId, and queue at most one waiting run:

settings:
  concurrency:
    key: "{{ workflow.id }}-{{ event.conversationId }}"
    strategy: queue
    max: 1
    queue-size: 1
		

Writes that arrive while a run is waiting are skipped, and the skipped runs appear in the workflow's execution history.

A workflow's own writes to the conversation don't trigger it again. By default, on.workflowEvents skips a run when the workflow is already part of the current event chain. This also covers user messages and agent runs that the workflow started. If you set on.workflowEvents: allow-all, add a condition that stops repeated runs.

Not every write a workflow causes has event.source set to workflow:

To ignore every write that originated from a workflow run, set on.workflowEvents: ignore.

Fire when an AlertZero investigation receives a user message:

triggers:
  - type: ai.conversation.updated
    on:
      condition: 'event.templateId: "investigation" and event.eventTypes: "user_message"'
		

When a workflow's own steps cause an event that its trigger listens for, executions can chain together (workflow A emits an event, which runs workflow B, which emits an event that runs A again). Left unchecked, these chains can loop or generate load. Event-driven triggers give you controls to manage this, with safe defaults.

Use on.workflowEvents on any event-driven trigger to control whether events that originated from a workflow run can fire this trigger:

triggers:
  - type: cases.caseUpdated
    on:
      # React only to case updates made by people, not updates made by workflows
      workflowEvents: ignore
		

Regardless of the value, the execution engine enforces a maximum event-chain depth as a final safety net against runaway chains.

If a workflows.failed handler fails, it can trigger itself. In addition to the controls above, every failure event includes event.workflow.isErrorHandler, which is true when the failed workflow was itself a handler. Filter on this field to skip handling your own failures:

triggers:
  - type: workflows.failed
    on:
      condition: "event.workflow.isErrorHandler : false"
		

In practice, keep handler workflows simpler than the workflows they monitor. A handler that only logs, opens a case, and notifies is less likely to fail than the automation it's handling.

You can test an event-driven workflow against a real event before enabling it. When you run a workflow from the editor, the Test workflow dialog shows a tab for each way to supply data, including an Event tab for event-driven triggers.

On the Event tab, browse events that have already occurred for your trigger type. Use the KQL search bar and time range to narrow the list, select an event from the results, and run the workflow against that event's payload. The execution then runs exactly as it would have when the event first occurred, so you can confirm your conditions and steps behave as expected.

• Triggers overview: All trigger types.
• Workflow authorization: Whose privileges event-driven workflows run with.
• Pass data and handle errors: Per-step on-failure strategies complement event-driven handlers.
• Monitor workflow execution: See what triggered each run and inspect the event payload.
• Cases steps: Open cases from your handler.
• Connect workflows to Kibana Universal Alerting: Learn how action policies invoke workflows for alerts, and when to use lifecycle triggers instead.
• Connect Elastic Agent Builder agents and Elastic Workflows: Other ways to use agents and workflows together.