Skip to main content

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.

$this->webhookUrl();
$this->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): 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' => 'workflows',

After this change, webhooks will be accessible under:

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