Events Reference

Workflowable dispatches Laravel events at every workflow lifecycle point. Listen to these for notifications, logging, metrics, and integrations.

Event List

All events are in the Workflowable\Workflowable\Events namespace.

Event	When	Properties
WorkflowStarted	Workflow instance created	$instance, $userId
StepStarted	Step begins execution	$execution
StepCompleted	Step succeeds	$execution, $result
StepRetrying	Step about to retry	$execution, $attempt, $delaySeconds
StepFailed	Step fails	$execution, $exception, $willRetry
TransitionTriggered	Moving to next step	$instance, $fromStep, $toStep, $condition
WorkflowCompleted	Workflow finishes successfully	$instance, $result
WorkflowFailed	Workflow fails	$instance, $exception

Listening to Events

In a Service Provider

use Workflowable\Workflowable\Events\WorkflowCompleted;
use Workflowable\Workflowable\Events\StepFailed;

Event::listen(WorkflowCompleted::class, function ($event) {
    Log::info("Workflow completed: {$event->instance->id}");
});

Event::listen(StepFailed::class, function ($event) {
    if (!$event->willRetry) {
        AlertService::notify("Step failed permanently: {$event->execution->step_name}");
    }
});

As Listener Classes

// EventServiceProvider
protected $listen = [
    \Workflowable\Workflowable\Events\WorkflowCompleted::class => [
        \App\Listeners\LogWorkflowCompletion::class,
    ],
    \Workflowable\Workflowable\Events\StepFailed::class => [
        \App\Listeners\AlertOnStepFailure::class,
    ],
];

Common Patterns

Monitoring Failed Steps

Event::listen(StepFailed::class, function ($event) {
    if ($event->willRetry) {
        Log::warning("Step retrying", [
            'step' => $event->execution->step_name,
            'attempt' => $event->execution->attempts,
        ]);
    } else {
        Log::error("Step failed permanently", [
            'step' => $event->execution->step_name,
            'error' => $event->exception->getMessage(),
        ]);
    }
});

Tracking Workflow Metrics

Event::listen(WorkflowStarted::class, fn ($e) =>
    Metrics::increment('workflow.started', ['name' => $e->instance->workflow->name])
);

Event::listen(WorkflowCompleted::class, fn ($e) =>
    Metrics::increment('workflow.completed', ['name' => $e->instance->workflow->name])
);

Event::listen(WorkflowFailed::class, fn ($e) =>
    Metrics::increment('workflow.failed', ['name' => $e->instance->workflow->name])
);