Configuration Options

This page provides a comprehensive reference of all configuration options available in the config/workflows.php file.

Publishing Configuration

Publish the configuration file to customize it:

php artisan vendor:publish --provider="Workflow\Providers\WorkflowServiceProvider"

This creates config/workflows.php in your Laravel application.

Workflows Folder

workflows_folder

string

default:"Workflows"

The directory within your application where workflow classes are stored. Relative to the app directory.

'workflows_folder' => 'Workflows',

Database Models

Customize the Eloquent models used for persisting workflow data.

stored_workflow_model

string

default:"Workflow\\Models\\StoredWorkflow::class"

The model class for workflow instances.

'stored_workflow_model' => Workflow\Models\StoredWorkflow::class,

stored_workflow_exception_model

string

The model class for workflow exceptions.

'stored_workflow_exception_model' => Workflow\Models\StoredWorkflowException::class,

stored_workflow_log_model

string

default:"Workflow\\Models\\StoredWorkflowLog::class"

The model class for activity execution logs.

'stored_workflow_log_model' => Workflow\Models\StoredWorkflowLog::class,

stored_workflow_signal_model

string

default:"Workflow\\Models\\StoredWorkflowSignal::class"

The model class for workflow signals.

'stored_workflow_signal_model' => Workflow\Models\StoredWorkflowSignal::class,

stored_workflow_timer_model

string

default:"Workflow\\Models\\StoredWorkflowTimer::class"

The model class for workflow timers.

'stored_workflow_timer_model' => Workflow\Models\StoredWorkflowTimer::class,

Database Tables

workflow_relationships_table

string

default:"workflow_relationships"

The database table name for storing parent-child workflow relationships.

'workflow_relationships_table' => 'workflow_relationships',

Serialization

serializer

string

default:"Workflow\\Serializers\\Y::class"

The serializer class used to serialize and deserialize workflow data. The Y serializer provides efficient serialization with support for complex PHP types.

'serializer' => Workflow\Serializers\Y::class,

Data Retention

prune_age

string

default:"1 month"

How long to keep completed workflow data before it can be pruned. Uses PHP’s strtotime compatible format.

'prune_age' => '1 month',

Examples:

'7 days'
'2 weeks'
'3 months'
'1 year'

Webhook Configuration

Configure webhook endpoints for external integrations.

Webhook Route

webhooks_route

string

default:"webhooks"

The base route path for webhook endpoints. Can be overridden with the WORKFLOW_WEBHOOKS_ROUTE environment variable.

'webhooks_route' => env('WORKFLOW_WEBHOOKS_ROUTE', 'webhooks'),

Environment Variable:

WORKFLOW_WEBHOOKS_ROUTE=webhooks

Webhook Authentication

webhook_auth.method

string

default:"none"

The authentication method for webhook requests. Can be overridden with the WORKFLOW_WEBHOOKS_AUTH_METHOD environment variable.Options:

none - No authentication (not recommended for production)
signature - HMAC signature verification
token - Bearer token authentication
custom - Custom authentication class

'webhook_auth' => [
    'method' => env('WORKFLOW_WEBHOOKS_AUTH_METHOD', 'none'),
],

Environment Variable:

WORKFLOW_WEBHOOKS_AUTH_METHOD=signature

Signature Authentication

Used when webhook_auth.method is set to signature.

webhook_auth.signature.header

string

default:"X-Signature"

The HTTP header containing the webhook signature. Can be overridden with the WORKFLOW_WEBHOOKS_SIGNATURE_HEADER environment variable.

'webhook_auth' => [
    'signature' => [
        'header' => env('WORKFLOW_WEBHOOKS_SIGNATURE_HEADER', 'X-Signature'),
    ],
],

Environment Variable:

WORKFLOW_WEBHOOKS_SIGNATURE_HEADER=X-Signature

webhook_auth.signature.secret

string

default:"null"

The secret key used to generate and verify webhook signatures. Should be set via the WORKFLOW_WEBHOOKS_SECRET environment variable.

'webhook_auth' => [
    'signature' => [
        'secret' => env('WORKFLOW_WEBHOOKS_SECRET'),
    ],
],

Environment Variable:

WORKFLOW_WEBHOOKS_SECRET=your-secret-key-here

Token Authentication

Used when webhook_auth.method is set to token.

webhook_auth.token.header

string

default:"Authorization"

The HTTP header containing the authentication token. Can be overridden with the WORKFLOW_WEBHOOKS_TOKEN_HEADER environment variable.

'webhook_auth' => [
    'token' => [
        'header' => env('WORKFLOW_WEBHOOKS_TOKEN_HEADER', 'Authorization'),
    ],
],

Environment Variable:

WORKFLOW_WEBHOOKS_TOKEN_HEADER=Authorization

webhook_auth.token.token

string

default:"null"

The bearer token expected in webhook requests. Should be set via the WORKFLOW_WEBHOOKS_TOKEN environment variable.

'webhook_auth' => [
    'token' => [
        'token' => env('WORKFLOW_WEBHOOKS_TOKEN'),
    ],
],

Environment Variable:

WORKFLOW_WEBHOOKS_TOKEN=your-bearer-token

Custom Authentication

Used when webhook_auth.method is set to custom.

webhook_auth.custom.class

string

default:"null"

The fully qualified class name of a custom webhook authentication handler. Can be overridden with the WORKFLOW_WEBHOOKS_CUSTOM_AUTH_CLASS environment variable.

'webhook_auth' => [
    'custom' => [
        'class' => env('WORKFLOW_WEBHOOKS_CUSTOM_AUTH_CLASS', null),
    ],
],

Environment Variable:

WORKFLOW_WEBHOOKS_CUSTOM_AUTH_CLASS=App\Http\Middleware\CustomWebhookAuth

Complete Configuration Example

Here’s the complete default configuration file:

<?php

return [
    'workflows_folder' => 'Workflows',

    'stored_workflow_model' => Workflow\Models\StoredWorkflow::class,

    'stored_workflow_exception_model' => Workflow\Models\StoredWorkflowException::class,

    'stored_workflow_log_model' => Workflow\Models\StoredWorkflowLog::class,

    'stored_workflow_signal_model' => Workflow\Models\StoredWorkflowSignal::class,

    'stored_workflow_timer_model' => Workflow\Models\StoredWorkflowTimer::class,

    'workflow_relationships_table' => 'workflow_relationships',

    'serializer' => Workflow\Serializers\Y::class,

    'prune_age' => '1 month',

    'webhooks_route' => env('WORKFLOW_WEBHOOKS_ROUTE', 'webhooks'),

    'webhook_auth' => [
        'method' => env('WORKFLOW_WEBHOOKS_AUTH_METHOD', 'none'),

        'signature' => [
            'header' => env('WORKFLOW_WEBHOOKS_SIGNATURE_HEADER', 'X-Signature'),
            'secret' => env('WORKFLOW_WEBHOOKS_SECRET'),
        ],

        'token' => [
            'header' => env('WORKFLOW_WEBHOOKS_TOKEN_HEADER', 'Authorization'),
            'token' => env('WORKFLOW_WEBHOOKS_TOKEN'),
        ],

        'custom' => [
            'class' => env('WORKFLOW_WEBHOOKS_CUSTOM_AUTH_CLASS', null),
        ],
    ],
];

Environment Variables Summary

Variable	Description	Default
`WORKFLOW_WEBHOOKS_ROUTE`	Webhook base route	`webhooks`
`WORKFLOW_WEBHOOKS_AUTH_METHOD`	Authentication method	`none`
`WORKFLOW_WEBHOOKS_SIGNATURE_HEADER`	Signature header name	`X-Signature`
`WORKFLOW_WEBHOOKS_SECRET`	Signature secret key	-
`WORKFLOW_WEBHOOKS_TOKEN_HEADER`	Token header name	`Authorization`
`WORKFLOW_WEBHOOKS_TOKEN`	Bearer token	-
`WORKFLOW_WEBHOOKS_CUSTOM_AUTH_CLASS`	Custom auth class	-

WorkflowOptions

In addition to global configuration, you can specify per-workflow options using the WorkflowOptions class:

use Workflow\WorkflowOptions;

$options = new WorkflowOptions(
    connection: 'redis',
    queue: 'workflows'
);

Workflow::start(MyWorkflow::class, ['data'], $options);

connection

string

default:"null"

The queue connection to use for this specific workflow. If null, uses the default queue connection.

queue

string

default:"null"

The queue name to use for this specific workflow. If null, uses the default queue.

See the Queue Configuration page for more details on using WorkflowOptions.

Getting Started

Core Concepts

Workflow Patterns

Advanced Features

Configuration

Monitoring

Examples

Configuration Options

Publishing Configuration