Download the PHP package bambamboole/laravel-webhooks without Composer

Laravel Webhooks

Attribute-driven outgoing webhooks for Laravel: annotate event classes, manage subscriptions in the database, and deliver signed payloads through spatie/laravel-webhook-server.

Installation

Delivery goes through spatie/laravel-webhook-server, which is installed as a dependency. The webhook_subscriptions and webhook_deliveries migrations run automatically. Publish the config if you need to change defaults:

Defining webhook events

Annotate any class with #[WebhookEvent] and give it a payload method. By default the package scans app/Events; adjust webhooks.scan_paths in the config to change that.

Every delivery wraps the payload in a stable envelope. An optional webhookLinks() method adds JSON:API-style resource links so receivers can navigate back to (or re-fetch) the resources an event is about; the links key is omitted when an event defines none. Links live in the signed body, so receivers can trust them after verifying the signature:

WebhookEventRegistry::all() returns the discovered definitions, which an app can use to power its own webhook setup UI:

Managing subscriptions

Subscriptions live in the webhook_subscriptions table via the shipped Eloquent model. events holds wildcard patterns: invoice.paid matches exactly, invoice.* matches every invoice event, and '*' subscribes to everything. Secrets are encrypted at rest and used to sign deliveries.

Verify an endpoint by sending a signed ping event through the normal delivery pipeline:

To source subscriptions from somewhere else, bind your own repository — the database repository is only a default (bindIf):

Dispatching

Webhook event classes are regular Laravel events — fire them and the package delivers them. Listeners for every discovered #[WebhookEvent] class are registered automatically:

Discovery scans the configured paths at every boot. Cache the result in production like you cache routes:

Alternatively set webhooks.auto_listen to false and wire the dispatcher yourself:

Each active subscription for the event receives one signed call through spatie's queue-backed webhook server. Calls are signed with the subscription secret (unsigned when no secret is set) and include a timestamp against replay attacks (webhooks.dispatcher.use_timestamp).

Delivery log

Every call attempt is recorded in the webhook_deliveries table (UUIDv7 keys): event name, url, payload, attempt, status, HTTP response status, and error details. Retries of the same call share a call_uuid. The status is succeeded, failed (a retry follows), or final_failed (retries exhausted).

Resend a delivery — the stored payload goes out again using the subscription's current url, secret, and headers, so rotated secrets and moved endpoints are honored:

Calls dispatched through spatie's webhook server directly (without this package's dispatcher) are not recorded.

The log is prunable: rows older than webhooks.deliveries.prune_after_days (default 30, null keeps them forever) are removed when your app schedules pruning:

Custom model classes

Both Eloquent models can be replaced with app-level subclasses via webhooks.models — useful for adding tenancy, global scopes, or extra relations. Every internal read and write (delivery recording, subscription matching, the subscription relation) resolves through this config; each class must extend the package model it replaces:

Development

License

MIT