README

A comprehensive webhook management package for Laravel applications. Easily manage, track, and process incoming webhooks with built-in support for workspace and project scoping.

Features

Webhook Management: Complete CRUD operations for webhooks.
Secure Ingress: Automatic token generation for secure, unique webhook endpoints.
Signed Outbound Delivery: Queued, retried, HMAC-signed delivery of events to customer URLs.
Polymorphic Ownership: Any model (team, workspace, user, ...) can own a webhook.
Event Tracking: Logs all incoming webhook payloads, headers, and processing status.
API Ready: Comes with pre-configured controllers and routes for rapid development.

Installation

You can install the package via composer:

composer require whilesmart/eloquent-webhooks

You should publish and run the migrations with:

php artisan vendor:publish --tag="webhooks-migrations"
php artisan migrate

You can publish the config file with:

php artisan vendor:publish --tag="webhooks-config"

This is the contents of the published config file:

return [
    // Use UUID primary keys instead of auto-incrementing integers.
    'uuids' => (bool) env('WEBHOOKS_UUIDS', false),

    'register_routes' => env('WEBHOOKS_REGISTER_ROUTES', true),
    'route_prefix' => env('WEBHOOKS_ROUTE_PREFIX', ''),
    'route_middleware' => ['auth:sanctum'],
    'ingress_middleware' => [],

    // Signed, retried outbound delivery.
    'signing' => [
        'header' => env('WEBHOOKS_SIGNATURE_HEADER', 'X-Webhook-Signature'),
        'algo' => env('WEBHOOKS_SIGNATURE_ALGO', 'sha256'),
    ],
    'delivery' => [
        'timeout' => (int) env('WEBHOOKS_DELIVERY_TIMEOUT', 10),
        'max_attempts' => (int) env('WEBHOOKS_DELIVERY_MAX_ATTEMPTS', 6),
        'backoff' => [10, 60, 300, 1800, 7200, 21600],
        'queue' => env('WEBHOOKS_DELIVERY_QUEUE', null),
        'connection' => env('WEBHOOKS_DELIVERY_CONNECTION', null),
    ],
    'auto_disable_after' => (int) env('WEBHOOKS_AUTO_DISABLE_AFTER', 15),
];

Usage

Managing Webhooks

The package provides a Webhook model that you can use to manage your webhooks.

use Whilesmart\Webhooks\Models\Webhook;

$webhook = Webhook::create([
    'name' => 'My Webhook',
    'owner_type' => $team->getMorphClass(), // any model may own a webhook
    'owner_id' => $team->id,
    'created_by_type' => $user->getMorphClass(), // optional creator audit
    'created_by_id' => $user->id,
    'is_active' => true,
]);

// Get the unique ingress URL
echo $webhook->url; // https://your-app.com/webhooks/ingress/{token}

Webhook Ingress

ingress_middleware controls middleware on POST /webhooks/ingress/{token}. It defaults to [] and does not inherit route_middleware, which protects management routes. The receiving controller checks the URL token and requires an active webhook; callers do not need a Sanctum login.

To add throttling, set this in your published config/webhooks.php:

'ingress_middleware' => ['throttle:60,1'],

This applies Laravel's 60-request-per-minute throttle. Application middleware for provider signature checks can also go in this list. The package does not verify incoming signatures automatically. Application-wide middleware still applies.

Both route groups use route_prefix; setting register_routes to false disables both. See route configuration.

Incoming webhooks are sent to a unique URL containing a secure token. When a webhook is triggered:

The token is validated.
The trigger_count and last_triggered_at fields are updated.
A WebhookEvent is recorded containing the payload and headers.
If whilesmart/activities is installed, an activity log is automatically created.

Incoming events keep the parsed request fields in payload. The package does not reserve keys or choose an application-specific payload structure.

Keeping raw bodies in an application

Applications with a custom incoming handler can use RawPayload to preserve exact request bytes inside a JSON value:

use Whilesmart\Webhooks\Support\RawPayload;

$envelope = RawPayload::encode($request->getContent());
$event->payload = $envelope;
$event->save();

$originalBody = RawPayload::decode($event->payload);

The application chooses where to store this envelope and how its readers consume it. The default package ingress does not use it. Encoding produces:

{"raw_body": "{\"event\": \"opened\"}", "encoding": "utf-8"}

Non-UTF-8 bodies use base64. Decoding returns the original bytes, or null for an unsupported envelope. It does not parse JSON or form data and does not verify signatures.

Outbound Webhooks

Outgoing webhooks deliver your application's events to a customer-supplied URL. Create one with direction set to outgoing, the destination url, and the subscribed_events it should receive (omit subscribed_events to receive all):

$webhook = Webhook::create([
    'user_id' => $user->id,                 // creator (audit)
    'owner_type' => $team->getMorphClass(), // the owner that scopes the webhook
    'owner_id' => $team->id,
    'direction' => Webhook::DIRECTION_OUTGOING,
    'url' => 'https://customer.example.com/hooks',
    'subscribed_events' => ['whatsapp.message.received', 'whatsapp.message.status'],
]);
// $webhook->secret is generated automatically and used to sign deliveries.

Fire an event to every matching active webhook:

app(WebhookDispatcher::class)->dispatch(
    'whatsapp.message.received',
    ['from' => '+15551234567', 'text' => 'hi'],
    ['owner_type' => $team->getMorphClass(), 'owner_id' => $team->id],
);

// Or, on a model using the HasWebhooks trait:
$team->triggerWebhook('whatsapp.message.received', $payload);

Each match creates a WebhookDelivery and queues a DeliverWebhook job that POSTs the JSON payload with these headers:

X-Webhook-Id, X-Webhook-Event, X-Webhook-Delivery (stable id for deduplication), X-Webhook-Timestamp
X-Webhook-Signature: sha256=<hmac> where the HMAC is hash_hmac('sha256', "{timestamp}.{body}", secret) (header name and algorithm configurable)

Non-2xx responses, timeouts, and connection errors are retried with exponential backoff up to delivery.max_attempts; after auto_disable_after consecutive failures the webhook is deactivated and a WebhookDisabled event is emitted. Run php artisan webhooks:retry-stuck (e.g. on a schedule) to re-enqueue any deliveries whose retry is due. Tune everything under the delivery, signing, and auto_disable_after keys in config/webhooks.php.

API Endpoints

By default, the package registers the following routes (protected by auth:sanctum):

Management Routes

GET /webhooks: List all webhooks for the authenticated user.
POST /webhooks: Create a new webhook.
GET /webhooks/{id}: Get webhook details.
PATCH /webhooks/{id}: Update a webhook (or regenerate its token).
DELETE /webhooks/{id}: Soft delete a webhook.
GET /webhooks/{id}/events: List event history for a webhook.

The built-in CRUD routes scope webhooks to the authenticated user as owner. To manage webhooks owned by another model (a team, workspace, etc.), set the owner morph directly and authorize access with your own policy.

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

License

The MIT License (MIT). Please see License File for more information.

whilesmart / eloquent-webhooks

Package info

Security

Statistics