Workflow Event Bus — Overview
The workflow event bus provides a decoupled publish/subscribe channel for workflow lifecycle events. Build integrations, webhooks, and audit systems that react to workflow state changes without coupling to the engine internals.
What Is the Workflow Event Bus?
The event bus is an in-process publish/subscribe mechanism scoped to the ProcessEngine. It carries two categories of events:
Built-In Lifecycle Events
Published automatically by the engine — WorkflowStarted, WorkflowCompleted, WorkflowFailed, WorkflowPaused, WorkflowResumed. You do not publish these; you subscribe to them.
Custom Domain Events
Published by your node executors — e.g., OrderApproved, DocumentProcessed. Define a class extending WorkflowEvent, inject IWorkflowEventBus, and call PublishAsync.
Event Bus vs. Node Event Subscribers
| Aspect | IWorkflowEventBus | INodeEventSubscriber |
|---|---|---|
| Granularity | Workflow-level (started, paused, completed) | Node-level (before/after each node) |
| Who publishes | Engine (built-ins) + node executors (custom) | Engine always (automatic) |
| Custom events | Yes — define and publish any WorkflowEvent | No — only lifecycle hooks |
| Subscriber interface | IWorkflowEventHandler<TEvent> | INodeEventSubscriber |
| Use for audit logging | Workflow-level audit | Per-node audit |
Key Constraints
Architecture Diagram
Engine publishes WorkflowStarted
ProcessEngine.StartAsync() calls IWorkflowEventBus.PublishAsync(new WorkflowStarted(...))
Dispatcher resolves handlers
WorkflowEventDispatcher finds all IWorkflowEventHandler<WorkflowStarted> from DI
Handlers execute synchronously
Each handler's HandleAsync() is awaited in registration order. Exceptions are isolated per handler.
Common Use Cases
| Use Case | Event(s) Consumed | Handler Action |
|---|---|---|
| Webhook delivery | WorkflowCompleted, WorkflowFailed | POST to configured webhook URL |
| Workflow-level audit | All built-in events | Write audit record to DB |
| Billing / usage metering | WorkflowStarted, WorkflowCompleted | Increment tenant execution counter |
| Dashboard live update | WorkflowStarted, WorkflowCompleted | Push SignalR notification to UI |
| Domain notifications | Custom event: OrderApproved | Send email / Slack message |