Inštalácia

Pridajte balík a spustite inštalátor. Service provider a alias fasády Webhooks sa zaregistrujú automaticky:

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

webhooks:install zverejní konfiguráciu, päť migrácií webhookov a migrácie Sentinelu — deduplikácia prichádzajúcich správ a idempotentný middleware jobov používajú tabuľku sentinel_idempotency_keys. Migrácie sa z balíka nenačítavajú: pred migráciou ich zverejnite (inštalátor to urobí). Ak majú vlastníci alebo tabuľky balíka používať kľúče uuid či ulid, nastavte najprv webhooks.key_type a webhooks.primary_key_type (pozrite Konfigurácia).

Tagy na zverejnenie

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

Prvý prijatý webhook

Jeden endpoint na odosielateľa. Odosielateľovi dajte URL adresu a tajný kľúč — ten sa zobrazí len raz:

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

Alias handlera naviažte v config/webhooks.php a napíšte 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
        }
    }
}

Prvý odoslaný webhook

URL adresa patrí príjemcovi vášho zákazníka — doručenie je podpísané, opakované, obmedzené a chránené pred SSRF. Ochrana adresu preloží už pri uložení endpointu, preto použite skutočnú https adresu, ktorá sa preloží na verejného hostiteľa; vymyslené meno sa odmietne:

// $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]);

Worker frontu a plánovač

Doručenia sa spracúvajú len vo fronte: prichádzajúca trasa odpovie 202 a skončí, handler beží v ProcessInboundDelivery a každý odchádzajúci pokus v DeliverWebhook. Spustite worker pre webhooks.queue.connection a jeho fronty a spustite plánovač Laravelu — provider plánuje webhooks:retry každú minútu a webhooks:prune denne, oba s withoutOverlapping()->onOneServer(). Obmedzené a dlho odložené doručenia posúva ďalej len webhooks:retry.

• retry_after spojenia musí byť dlhší ako DeliverWebhook::$timeout (celkový limit odosielania + 20 s) aj ako inbound.handler.timeout — webhooks:doctor kontroluje oboje.
• Úložisko http-client-rate-limits musí byť zdieľané (cache alebo redis), aby obmedzenie na endpoint platilo naprieč workermi; predvolené úložisko v pamäti platí len v rámci procesu.
• Cache úložisko prichádzajúcich limitérov a úložisko idempotencie Sentinelu musia byť zdieľané — nikdy array.
• Front sync funguje pre testy a malé aplikácie, no spracovanie potom beží v požiadavke; webhooks:doctor upozorní.

Za proxy a limit tela

Za load balancerom alebo CDN nastavte dôveryhodné proxy Laravelu: strážca odmietnutí počíta podľa endpointu a IP klienta a bez nich by všetci odosielatelia zdieľali IP proxy.

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

Request::capture() v Laraveli prečíta a dekóduje celé telo JSON požiadavky ešte pred akýmkoľvek middleware, trasou či kódom balíka — kontrola 256 KB v balíku obmedzuje prácu s podpisom a ukladanie, nie toto prvé čítanie. Obmedzte preto telo na webovom serveri pre prefix prichádzajúcej trasy: nginx client_max_body_size (alebo Apache LimitRequestBody) mierne nad inbound.max_payload_bytes_ceiling (1 MB).

Kontrola nastavenia

php artisan webhooks:doctor

Odhalí spracovanie v požiadavke, nestále úložiská limitérov a idempotencie, zastavený pravidelný beh opakovaní a ďalšie — pozrite Príkazy Artisan.