Webhooks

Laravel Workflow provides webhooks that allow external systems to start workflows and send signals dynamically. This feature enables seamless integration with external services, APIs, and automation tools.

Enabling Webhooks

To enable webhooks in Laravel Workflow, register the webhook routes in your application’s routes file (routes/web.php or routes/api.php):

use Workflow\Webhooks;

Webhooks::routes();

By default, webhooks will:

• Auto-discover workflows in the app/Workflows folder.
• Expose webhooks to workflows marked with #[Webhook] at the class level.
• Expose webhooks to signal methods marked with #[Webhook].

Starting a Workflow via Webhook

To expose a workflow as a webhook, add the #[Webhook] attribute on the class itself.

use Workflow\Webhook;
use Workflow\Workflow;

#[Webhook]
class OrderWorkflow extends Workflow
{
    public function execute($orderId)
    {
        // your code here
    }
}

Webhook URL

POST /webhooks/start/order-workflow

Example Request

curl -X POST "https://example.com/webhooks/start/order-workflow" \
     -H "Content-Type: application/json" \
     -d '{"orderId": 123}'

Sending a Signal via Webhook

To allow external systems to send signals to a workflow, add the #[Webhook] attribute on the method.

use Workflow\SignalMethod;
use Workflow\Webhook;
use Workflow\Workflow;

class OrderWorkflow extends Workflow
{
    protected bool $shipped = false;

    #[SignalMethod]
    #[Webhook]
    public function markAsShipped()
    {
        $this->shipped = true;
    }
}

Webhook URL

POST /webhooks/signal/order-workflow/{workflowId}/mark-as-shipped

Example Request

curl -X POST "https://example.com/webhooks/signal/order-workflow/1/mark-as-shipped" \
     -H "Content-Type: application/json"

Webhook URL Helper

The $this->webhookUrl() helper generates webhook URLs for starting workflows or sending signals.

$activity->webhookUrl();
$activity->webhookUrl('signalMethod');

Parameters

• string $signalMethod = '' (optional)

If empty, returns the URL for starting the workflow.

If provided, returns the URL for sending a signal to an active workflow instance.

use Workflow\Activity;

class ShipOrderActivity extends Activity
{
    public function execute(string $email, StoredWorkflow $storedWorkflow): void
    {
        $startUrl = $this->webhookUrl();
        // $startUrl = '/webhooks/start/order-workflow';

        $signalUrl = $this->webhookUrl('markAsShipped');
        // $signalUrl = '/webhooks/signal/order-workflow/{workflowId}/mark-as-shipped';
    }
}

Webhook Authentication

By default, webhooks don't require authentication but this can be configured in config/workflows.php.

Authentication Methods

Laravel Workflow supports:

1. No Authentication (none)
2. Token-based Authentication (token)
3. HMAC Signature Verification (signature)

Token Authentication

For token authentication, webhooks require a valid API token in the request headers. The default header is Authorization but you can change this in the configuration settings.

Example Request

curl -X POST "https://example.com/webhooks/start/order-workflow" \
     -H "Content-Type: application/json" \
     -H "Authorization: your-api-token" \
     -d '{"orderId": 123}'

HMAC Signature Authentication

For HMAC authentication, Laravel Workflow verifies requests using a secret key. The default header is X-Signature but this can also be changed.

Example Request

BODY='{"orderId": 123}'
SIGNATURE=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "your-secret-key" | awk '{print $2}')

curl -X POST "https://example.com/webhooks/start/order-workflow" \
     -H "Content-Type: application/json" \
     -H "X-Signature: $SIGNATURE" \
     -d "$BODY"

Configuring Webhook Routes

By default, webhooks are accessible under /webhooks. You can customize the route path in config/workflows.php:

'webhooks_route' => 'api/webhooks',