Všetky balíky
Webhooks for Laravel
Konfigurácia
Balík funguje bez akejkoľvek konfigurácie. Ak chcete niečo zmeniť, zverejnite config/webhooks.php s --tag=webhooks-config (zobrazené bez komentárov):
use RoundlyConsulting\Webhooks\Http\Resources\WebhookOwnerResource;
use RoundlyConsulting\Webhooks\Models\InboundDelivery;
use RoundlyConsulting\Webhooks\Models\InboundEndpoint;
use RoundlyConsulting\Webhooks\Models\OutboundAttempt;
use RoundlyConsulting\Webhooks\Models\OutboundDelivery;
use RoundlyConsulting\Webhooks\Models\OutboundEndpoint;
use RoundlyConsulting\Webhooks\Schemes\DefaultScheme;
use RoundlyConsulting\Webhooks\Schemes\Rfc9421Scheme;
use RoundlyConsulting\Webhooks\Support\KeyRedactingSanitizer;
return [
'key_type' => env('WEBHOOKS_KEY_TYPE', 'bigint'),
'primary_key_type' => env('WEBHOOKS_PRIMARY_KEY_TYPE', 'bigint'),
'models' => [
'inbound_endpoint' => InboundEndpoint::class,
'inbound_delivery' => InboundDelivery::class,
'outbound_endpoint' => OutboundEndpoint::class,
'outbound_delivery' => OutboundDelivery::class,
'outbound_attempt' => OutboundAttempt::class,
],
'tables' => [
'inbound_endpoints' => 'webhook_inbound_endpoints',
'inbound_deliveries' => 'webhook_inbound_deliveries',
'outbound_endpoints' => 'webhook_outbound_endpoints',
'outbound_deliveries' => 'webhook_outbound_deliveries',
'outbound_attempts' => 'webhook_outbound_attempts',
],
'resources' => [
'owner' => WebhookOwnerResource::class,
],
'queue' => [
'connection' => env('WEBHOOKS_QUEUE_CONNECTION'),
'queue' => env('WEBHOOKS_QUEUE_NAME'),
'inbound' => env('WEBHOOKS_INBOUND_QUEUE'),
'outbound' => env('WEBHOOKS_OUTBOUND_QUEUE'),
'max_delay' => 900,
],
'inbound' => [
'route' => [
// POST {prefix}/{key}. Off: mount your own route calling Webhooks::inbound()->receive().
'enabled' => env('WEBHOOKS_INBOUND_ROUTE', true),
'prefix' => 'webhooks',
'domain' => null,
// Never `web`: a sender has no session or CSRF token.
'middleware' => [],
// The base the endpoint URL is built on (e.g. behind a proxy); blank = route().
'url_base' => env('WEBHOOKS_INBOUND_URL'),
],
'tolerance' => 300,
'max_payload_bytes' => 262144,
'max_payload_bytes_ceiling' => 1048576,
'content_types' => ['application/json', 'application/*+json'],
'on_duplicate' => 'accept',
'accept_idempotency_header' => true,
'dedupe_ttl' => 604800,
'rate_limit' => [
'per_minute' => 600,
'rejected_per_minute' => 60,
'cache_store' => null,
],
'store_headers' => ['content-type', 'user-agent', 'webhook-id', 'webhook-timestamp'],
'requeue_after' => 60,
'handler' => [
'tries' => 3,
'backoff' => [10, 60, 300],
'timeout' => 60,
],
],
'outbound' => [
'allow_http' => env('WEBHOOKS_ALLOW_HTTP', false),
'verify_on_save' => true,
'envelope' => true,
'event_types' => [],
'max_payload_bytes' => 262144,
'max_response_bytes' => 4096,
'timeouts' => [
'connect' => 5,
'total' => 10,
],
'max_attempts' => 8,
'retry' => [
// delay(n) = min(base * multiplier^(n-1), cap) seconds, then ± jitter_permille.
'base' => 60,
'multiplier' => 4,
'cap' => 32400,
'jitter_permille' => 100,
'max_retry_after' => 86400,
'schedule' => null,
],
'rate_limit' => [
'per_minute' => 60,
],
'requeue_after' => 120,
'sweep_batch' => 1000,
'disable_after' => 5,
'disable_on_gone' => true,
'follow_redirects' => false,
'max_redirects' => 3,
'headers' => [
'allowed_overrides' => [],
],
// The User-Agent your receivers see. Blank = "{app.name} Webhooks".
'user_agent' => env('WEBHOOKS_USER_AGENT'),
],
'ssrf' => [
// Off only behind a filtering egress proxy you trust (webhooks:doctor warns).
'enabled' => env('WEBHOOKS_SSRF_GUARD', true),
'block_app_hosts' => true,
'app_hosts' => [],
'allowed_hosts' => [],
'blocked_hosts' => [],
'allowed_ranges' => [],
'blocked_ranges' => [],
'allowed_ports' => null,
],
'secrets' => [
'bytes' => 32,
'grace_seconds' => 86400,
'max_grace_seconds' => 604800,
],
'schemes' => [
'default' => DefaultScheme::class,
'rfc9421' => Rfc9421Scheme::class,
],
'rfc9421' => [
'profile' => 'default',
'outbound_key_id' => null,
],
'handlers' => [],
'sanitizer' => [
'class' => KeyRedactingSanitizer::class,
'redact_keys' => ['password', 'secret', 'token', 'api_key', 'authorization', 'card_number', 'cvc', 'ssn'],
'replacement' => '[redacted]',
],
'payloads' => [
'encrypt' => true,
'retention_days' => 30,
'delivery_retention_days' => 90,
],
'schedule' => [
'enabled' => true,
'retry' => 'everyMinute',
'prune' => 'daily',
],
];Prísne načítanie
- Každá hodnota sa načíta prísne: preklep alebo hodnota mimo rozsahu vyhodí InvalidConfigurationException z package-toolkit s názvom kľúča.
- Kľúč s triedou — schemes.*, handlers.*, sanitizer.class — ktorý neukazuje na inštancovateľnú implementáciu svojho kontraktu, vyhodí InvalidWebhooksConfigurationException, tiež s názvom kľúča.
- Prázdna hodnota (KEY=) znamená nenastavené a platí predvolená. Prepínače prijímajú true/false, 1/0, on/off a yes/no.
- Zoznamy celých čísel (handler.backoff, retry.schedule, ssrf.allowed_ports) prijímajú aj reťazec oddelený čiarkami („60,300,3600“).
Kľúče, modely a tabuľky
| Kľúč | Env | Predvolené | Účel |
|---|---|---|---|
key_type | WEBHOOKS_KEY_TYPE | bigint | bigint, uuid alebo ulid — typ kľúča modelov aplikácie, ktoré vlastnia endpointy (stĺpce morfu owner). Nastavte ho pred migráciou. |
primary_key_type | WEBHOOKS_PRIMARY_KEY_TYPE | bigint | bigint, uuid (UUIDv7) alebo ulid — vlastné id a cudzie kľúče tabuliek balíka. Pred migráciou. Id v komunikácii sú vždy ULID. |
models.* | — | the packaged models | inbound_endpoint, inbound_delivery, outbound_endpoint, outbound_delivery, outbound_attempt — náhrada musí rozširovať model balíka. |
tables.* | — | webhook_inbound_endpoints, … | Názvy piatich tabuliek; každý musí zodpovedať ^[A-Za-z_][A-Za-z0-9_.]{0,63}$. |
resources.owner | — | WebhookOwnerResource | Ako sa vlastník endpointu vykreslí v JSON resources — inštancovateľná podtrieda JsonResource. |
Front
| Kľúč | Env | Predvolené | Účel |
|---|---|---|---|
queue.connection | WEBHOOKS_QUEUE_CONNECTION | blank = default | Spojenie, ktoré používa každý job balíka. |
queue.queue | WEBHOOKS_QUEUE_NAME | blank = the connection’s default | Záložný front pre oba smery. |
queue.inbound | WEBHOOKS_INBOUND_QUEUE | blank = queue.queue | Front pre ProcessInboundDelivery. |
queue.outbound | WEBHOOKS_OUTBOUND_QUEUE | blank = queue.queue | Front pre DeliverWebhook. |
queue.max_delay | — | 900 | 1–43 200 s — najdlhšie oneskorený job; dlhšie opakovanie počká na pravidelný beh webhooks:retry (SQS nevie oneskoriť viac ako 900 s). |
Prijímanie
| Kľúč | Env | Predvolené | Účel |
|---|---|---|---|
inbound.route.enabled | WEBHOOKS_INBOUND_ROUTE | on | Trasa balíka POST {prefix}/{key}; vypnutá → pripojte si vlastnú. |
inbound.route.prefix | — | webhooks | Prefix trasy (lomky sa odstránia). |
inbound.route.domain | — | null | Doména trasy. |
inbound.route.middleware | — | [] | Názvy middleware — nikdy web: odosielateľ nemá session ani CSRF token. |
inbound.route.url_base | WEBHOOKS_INBOUND_URL | null = route() | Základ URL adries endpointov, ktoré sa vám zobrazia ({url_base}/{key}), napríklad za proxy. |
inbound.tolerance | — | 300 | 1–3 600 s — ako ďaleko od teraz môže byť podpísaná časová pečiatka, do minulosti aj budúcnosti. |
inbound.max_payload_bytes | — | 262144 | Limit veľkosti tela (256 KB), 1 – max_payload_bytes_ceiling. |
inbound.max_payload_bytes_ceiling | — | 1048576 | 1 – 67 108 864 — najviac, čo smie povoliť nastavenie konkrétneho endpointu (1 MB). |
inbound.content_types | — | application/json, application/*+json | Prijímané typy Content-Type (* je povolená v podtype, parametre sa ignorujú). |
inbound.on_duplicate | — | accept | accept odpovie na opakovanie 200 {"status":"duplicate"}; conflict odpovie 409. |
inbound.accept_idempotency_header | — | on | Použiť Idempotency-Key, keď schéma nenesie id doručenia. |
inbound.dedupe_ttl | — | 604800 | 60 – 2 592 000 s — ako dlho sa pamätajú id doručení (a odtlačky tiel pri nepodpísaných id) (7 dní). |
inbound.rate_limit.per_minute | — | 600 | Overené doručenia na endpoint za minútu. |
inbound.rate_limit.rejected_per_minute | — | 60 | Odmietnuté požiadavky na endpoint a IP klienta za minútu. |
inbound.rate_limit.cache_store | — | null = default store | Cache úložisko limitérov — musí byť zdieľané, nikdy array. |
inbound.store_headers | — | content-type, user-agent, webhook-id, webhook-timestamp | Hlavičky uložené s doručením; podpisové, prihlasovacie a cookie hlavičky sa vynechajú bez ohľadu na zoznam. |
inbound.requeue_after | — | 60 | Uložené doručenie, ktoré sa po tomto počte sekúnd nedostalo do frontu, zaradí pravidelný beh. |
inbound.handler.tries | — | 3 | 1–100 — ProcessInboundDelivery::$tries. |
inbound.handler.backoff | — | [10, 60, 300] | Sekundy medzi pokusmi spracovania (zoznam alebo reťazec oddelený čiarkami). |
inbound.handler.timeout | — | 60 | 1–86 400 s — časový limit jobu spracovania. |
Odosielanie
| Kľúč | Env | Predvolené | Účel |
|---|---|---|---|
outbound.allow_http | WEBHOOKS_ALLOW_HTTP | off | Okrem https aj http — len pre lokálny vývoj. |
outbound.verify_on_save | — | on | Preložiť a overiť URL pri vytvorení a úprave; vypnuté = všetky pravidlá okrem prekladu DNS. |
outbound.envelope | — | on | Zabaliť obsah do {"type","timestamp","data"}; vypnuté = obsah tak, ako je. |
outbound.event_types | — | [] | Známe typy; prázdne = akýkoľvek platný názov, neprázdne = len tieto (InvalidEventTypeException). |
outbound.max_payload_bytes | — | 262144 | Limit zakódovaného tela (PayloadTooLargeException). |
outbound.max_response_bytes | — | 4096 | 1 – 1 048 576 — koľko z odpovede príjemcu sa prečíta a uloží. |
outbound.timeouts.connect | — | 5 | 1–60 s — limit na pripojenie. |
outbound.timeouts.total | — | 10 | connect – 300 s — jeden rozpočet pre všetky kroky presmerovania; DeliverWebhook::$timeout je táto hodnota + 20. |
outbound.max_attempts | — | 8 | 1–25 pokusov na sériu doručenia. |
outbound.retry.base | — | 60 | delay(n) = min(base · multiplier^(n-1), cap). |
outbound.retry.multiplier | — | 4 | 1–100. |
outbound.retry.cap | — | 32400 | Najdlhšie vypočítané oneskorenie (9 h). |
outbound.retry.jitter_permille | — | 100 | 0–500 — náhodný rozptyl (± 10 %). |
outbound.retry.max_retry_after | — | 86400 | Najdlhší rešpektovaný Retry-After. |
outbound.retry.schedule | — | null | Explicitné oneskorenia namiesto vzorca ([60, 300, 3600]); za koncom sa opakuje posledná hodnota. |
outbound.rate_limit.per_minute | — | 60 | Požiadavky na endpoint za minútu (endpoint môže prepísať). |
outbound.requeue_after | — | 120 | Splatné doručenie, ktorého job mešká o toľko, sa odošle znova; každá ďalšia kópia čaká dvakrát dlhšie (najviac hodinu). |
outbound.sweep_batch | — | 1000 | 1 – 100 000 — najviac jobov odosielania, ktoré odošle jeden beh webhooks:retry. |
outbound.disable_after | — | 5 | Počet doručení po sebe, ktoré skončili ako failed, kým sa endpoint vypne. |
outbound.disable_on_gone | — | on | Odpoveď 410 Gone endpoint okamžite vypne. |
outbound.follow_redirects | — | off | Sledovať 307/308 (každý krok sa znova overí). |
outbound.max_redirects | — | 3 | 0–10. |
outbound.headers.allowed_overrides | — | [] | Rezervované vlastné hlavičky, ktoré endpoint smie nastaviť: host (len pri vypnutom ssrf.enabled), authorization. |
outbound.user_agent | WEBHOOKS_USER_AGENT | blank = "{app.name} Webhooks" | User-Agent, ktorý vidia príjemcovia (Laravel Webhooks, ak aplikácia nemá názov). |
Bezpečnosť odosielania (SSRF)
| Kľúč | Env | Predvolené | Účel |
|---|---|---|---|
ssrf.enabled | WEBHOOKS_SSRF_GUARD | on | Ochrana; vypnúť len za filtrujúcou výstupnou proxy, ktorej dôverujete. |
ssrf.block_app_hosts | — | on | Odmietnuť hostiteľa z app.url a ssrf.app_hosts. |
ssrf.app_hosts | — | [] | Ďalšie mená vašej vlastnej aplikácie. |
ssrf.allowed_hosts | — | [] | Presne alebo *.example.com; neprázdne znamená len týchto hostiteľov (aj tak sa preložia a overia). |
ssrf.blocked_hosts | — | [] | Vždy odmietnuté. |
ssrf.allowed_ranges | — | [] | IP alebo CIDR vyňaté z tabuľky privátnych sietí (lokálne 127.0.0.1/32). |
ssrf.blocked_ranges | — | [] | IP alebo CIDR vždy odmietnuté — blokovanie má prednosť pred povolením. |
ssrf.allowed_ports | — | null = any | Zoznam portov 1–65 535. |
Tajné kľúče, schémy a handlery
| Kľúč | Env | Predvolené | Účel |
|---|---|---|---|
secrets.bytes | — | 32 | 24–64 náhodných bajtov vo vygenerovanom tajnom kľúči (whsec_ + base64). |
secrets.grace_seconds | — | 86400 | Predvolené prechodné obdobie vyradeného tajného kľúča, 0 – max_grace_seconds. |
secrets.max_grace_seconds | — | 604800 | Najdlhšie prechodné obdobie, ktoré rotateSecret() prijme (0 – 31 536 000). |
schemes | — | default ⇒ DefaultScheme, rfc9421 ⇒ Rfc9421Scheme | Názov ⇒ trieda SignatureScheme; vlastné pridajte tu alebo cez Webhooks::schemes()->extend(). |
rfc9421.profile | — | default | Podpisový profil Sentinelu, voči ktorému overujú prichádzajúce endpointy RFC 9421 (scheme_options.profile endpointu má prednosť). |
rfc9421.outbound_key_id | — | null | Kľúč Sentinelu, ktorým podpisujú odchádzajúce endpointy RFC 9421 (scheme_options.key_id endpointu má prednosť). |
handlers | — | [] | Alias ⇒ trieda InboundHandler; closures cez Webhooks::handlers()->register(). |
Obsah, retencia a plánovanie
| Kľúč | Env | Predvolené | Účel |
|---|---|---|---|
sanitizer.class | — | KeyRedactingSanitizer | Trieda PayloadSanitizer spustená na každom prichádzajúcom obsahu pred uložením. |
sanitizer.redact_keys | — | password, secret, token, api_key, authorization, card_number, cvc, ssn | Názvy kľúčov, ktoré predvolený sanitizér začierni (bez ohľadu na veľkosť písmen). |
sanitizer.replacement | — | [redacted] | Hodnota, ktorú dostanú. |
payloads.encrypt | — | on | Šifrovať uložený obsah a telá kľúčom aplikácie. |
payloads.retention_days | — | 30 | 1–36 500 — obsah, telá a výňatky odpovedí sa potom vymažú. |
payloads.delivery_retention_days | — | 90 | 1–36 500 alebo null = ponechať — riadky doručení a pokusov (a zmazané endpointy, na ktoré nič neukazuje) sa potom zmažú. |
schedule.enabled | — | on | Provider naplánuje webhooks:retry a webhooks:prune. |
schedule.retry | — | everyMinute | everyMinute, everyTwoMinutes alebo everyFiveMinutes. |
schedule.prune | — | daily | hourly, daily alebo weekly. |
Nastavenia pre konkrétny endpoint
Niektoré nastavenia môžete prepísať pre jeden endpoint cez objekty volieb (limity nájdete v časti Správa endpointov):
| Nastavenie | InboundEndpointOptions | OutboundEndpointOptions |
|---|---|---|
| Limit za minútu | rateLimitPerMinute | rateLimitPerMinute |
| Veľkosť tela | maxPayloadBytes | — |
| Typy obsahu | contentTypes | — |
| Tolerancia časovej pečiatky | toleranceSeconds | — |
| Voľby schémy | schemeOptions (profile, id_header) | schemeOptions (key_id) |
| Popis | — | description |
Premenné prostredia
WEBHOOKS_KEY_TYPE=bigint
WEBHOOKS_PRIMARY_KEY_TYPE=bigint
WEBHOOKS_QUEUE_CONNECTION=
WEBHOOKS_QUEUE_NAME=
WEBHOOKS_INBOUND_QUEUE=
WEBHOOKS_OUTBOUND_QUEUE=
WEBHOOKS_INBOUND_ROUTE=true
WEBHOOKS_INBOUND_URL=
WEBHOOKS_ALLOW_HTTP=false
WEBHOOKS_USER_AGENT=
WEBHOOKS_SSRF_GUARD=truePrejavte lásku k open source
Tento balík je zadarmo pod licenciou MIT. Ak vám šetrí čas, jednorazový príspevok alebo členstvo na Patreone nám pomôže ho ďalej udržiavať, testovať a dokumentovať.
Ďalšie spôsoby podpory vrátane kryptomienOdoslaním daru súhlasíte s našimi podmienkami prijímania darov.
Chcete to zabudovať do svojho produktu?
Naše balíky integrujeme do zákazkových Laravel a AI riešení. Napíšte nám, na čom pracujete, a ozveme sa do 48 hodín.