Installation

Require the package and run the installer. The service provider and the Webhooks facade alias are auto-discovered:

composer require roundly-consulting/webhooks-for-laravel
php artisan webhooks:install      # config + webhooks migrations + sentinel migrations
php artisan migrate

webhooks:install publishes the config, the five webhooks migrations and Sentinel’s migrations — the inbound dedupe and the jobs’ idempotent middleware use Sentinel’s sentinel_idempotency_keys table. The migrations are not loaded from the package: publish them (the installer does) before migrating. Set webhooks.key_type and webhooks.primary_key_type first if your owners or the package tables should use uuid or ulid keys (see Configuration).

Publish tags

php artisan vendor:publish --tag=webhooks-translations

Receive your first webhook

One endpoint per sender. Give the sender the URL and the secret — the secret is shown once:

use RoundlyConsulting\Webhooks\Facades\Webhooks;

$inbound = Webhooks::for($team)->inbound()->create(handler: 'billing');
$inbound->url;     // https://app.test/webhooks/q8Zr…  (an unguessable 32-character key)
$inbound->secret;  // whsec_…  — never readable again

Bind the handler alias in config/webhooks.php and write the handler:

// config/webhooks.php
'handlers' => ['billing' => App\Webhooks\BillingWebhookHandler::class],

use RoundlyConsulting\Webhooks\Contracts\InboundHandler;
use RoundlyConsulting\Webhooks\DataTransferObjects\InboundWebhook;

final class BillingWebhookHandler implements InboundHandler
{
    public function handle(InboundWebhook $webhook): void
    {
        if ($webhook->type === 'invoice.paid') {
            // runs on the queue, once per delivery
        }
    }
}

Send your first webhook

The URL is your customer’s own receiver — signed, retried, throttled and SSRF-guarded. The guard resolves it when the endpoint is saved, so use a real https address that resolves to a public host; a made-up name is refused:

// $url — the https address your customer entered for their own receiver.
// The SSRF guard resolves it on save: it must be a public host that resolves.
$outbound = Webhooks::for($team)->outbound()->create($url, events: ['invoice.*']);
$outbound->secret; // whsec_… — hand it to the receiver once

Webhooks::send($outbound->endpoint, 'invoice.paid', ['invoice' => 42]);

A queue worker and the scheduler

Deliveries are processed only on the queue: the inbound route answers 202 and returns, the handler runs in ProcessInboundDelivery and every outbound attempt in DeliverWebhook. Run a worker for webhooks.queue.connection and its queues, and run Laravel’s scheduler — the provider schedules webhooks:retry every minute and webhooks:prune daily, both withoutOverlapping()->onOneServer(). Throttled and long-delayed deliveries move only through webhooks:retry.

• The connection’s retry_after must be longer than DeliverWebhook::$timeout (the outbound total timeout + 20 s) and than inbound.handler.timeout — webhooks:doctor checks both.
• The http-client-rate-limits store must be shared (cache or redis) for the per-endpoint outbound throttle to hold across workers; the default in-memory store is per process.
• The inbound limiters’ cache store and Sentinel’s idempotency store must be shared — never array.
• A sync queue works for tests and small apps but runs processing inside the request; webhooks:doctor warns.

Behind a proxy, and the body limit

Behind a load balancer or a CDN, configure Laravel’s trusted proxies: the inbound rejection guard counts per endpoint and client IP, and without them every sender shares the proxy’s IP.

// bootstrap/app.php — behind a load balancer or a CDN
->withMiddleware(function (Middleware $middleware): void {
    $middleware->trustProxies(at: [/* your proxies */]);
})

Laravel’s Request::capture() reads and decodes a JSON request’s whole body before any middleware, route or package code runs — the package’s 256 KB check bounds signature work and storage, not that first read. Bound the body at the web server for the inbound prefix: nginx client_max_body_size (or Apache LimitRequestBody) a little above inbound.max_payload_bytes_ceiling (1 MB).

Check the setup

php artisan webhooks:doctor

It flags processing inside the request, volatile limiter and idempotency stores, a stalled retry sweep and more — see Artisan commands.