Using Workflow Lifecycle Event Triggers

Overview

Workflow lifecycle event triggers let you automatically respond when workflows in your environment are created, updated, or published. These events capture changes to workflows themselves—not workflow executions—so you can build automation around workflow management.

In this article, we'll be covering the four workflow lifecycle events, their payloads, how to set up lifecycle event triggers, and common automation patterns.

Understanding workflow lifecycle events

gaiia publishes four workflow lifecycle events that can be used as event triggers:

• workflow.created: Fires when a new workflow is created
• workflow.status_changed: Fires when a workflow is enabled or disabled
• workflow.metadata_updated: Fires when a workflow's name, description, icon, or labels are changed
• workflow.published: Fires when a new workflow version is published (from a draft, direct save, or version restore)

The workflow.metadata_updated event only fires when the metadata actually changes. Saving a workflow without changing these fields will not trigger the event.

Setting up a workflow lifecycle trigger

1. Create a new workflow and select Event as the trigger type
2. Select the lifecycle event from the event picker (workflow.created, workflow.status_changed, workflow.metadata_updated, or workflow.published)
3. Configure your workflow logic to respond to the event
4. Access event data using state.input in your workflow nodes

The workflow will automatically fire whenever the selected lifecycle event occurs in your environment.

Common use cases

Monitoring workflow deployments

Send notifications when workflows are published:

• Trigger: workflow.published
• Format a message with the workflow name and version
• Send to a Slack channel or Teams for visibility

Tracking workflow creation

Log all new workflows for platform monitoring:

• Trigger: workflow.created
• Create an Activity Log comment with creator and timestamp
• Post to a monitoring channel or tracking database

Alerting on critical workflow changes

Watch for production workflows being disabled:

• Trigger: workflow.status_changed
• Check if the workflow is in a critical list using the Skip Execution Mapper
• If disabled, send an urgent alert to on-call

Auditing metadata changes

Track workflow renames and label changes for compliance:

• Trigger: workflow.metadata_updated
• Log changes to an audit database
• Update external documentation systems

Filtering lifecycle events

Use the skip execution mapper on your trigger to filter which lifecycle events actually execute your workflow. The skip execution mapper receives the event payload in state.input and returns true to skip execution or false to proceed.

Returning true skips execution; returning false proceeds with execution.

Accessing workflow details

Workflow lifecycle events provide the workflow's Global ID. To fetch additional details about the workflow, use the gaiia GraphQL API node with queries like:

query GetWorkflow($id: ID!) {
  workflow(id: $id) {
    id
    name
    description
    status
    trigger {
      type
    }
  }
}

Permissions

• View: Users need Workflows > View permission to see workflows that trigger these events
• Create: Users need Workflows > Edit permission to create workflows that respond to lifecycle events
• Execute: No special permissions are required for the lifecycle events themselves—they fire automatically when workflows change

Limitations

• Workflow lifecycle events capture changes to workflows, not workflow executions. To trigger on execution success or failure, use the workflowExecutionSuccess or workflowExecutionFailed events instead.
• The workflow.metadata_updated event only fires when the metadata diff is non-empty. Saving without changes will not trigger the event.
• Lifecycle events are published after the database transaction commits, so the workflow change is already persisted when your automation runs.