---
title: "Konfigurácia — Webhooks for Laravel | Roundly"
description: "Každý kľúč config/webhooks.php — kľúče a modely, fronty, prijímanie, odosielanie, SSRF, tajné kľúče, schémy, obsah správ a plánovanie."
url: https://roundly-consulting.com/sk/open-source/navody/webhooks-for-laravel/konfiguracia
language: sk
---

[Všetky balíky](https://roundly-consulting.com/sk/open-source.md)

[Webhooks for Laravel](https://roundly-consulting.com/sk/open-source/navody/webhooks-for-laravel.md)

# 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):

```php
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

```bash
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=true
```

## Prejavte 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 kryptomien](https://roundly-consulting.com/sk/podporte-nas.md)

Odoslaním daru súhlasíte s našimi [podmienkami prijímania darov](https://roundly-consulting.com/sk/podmienky-darov.md).

[Podporte našu open-source prácu (otvorí sa v novej karte)](https://donate.stripe.com/dRmeVe8FX5PF1Qd9pXcEw00) [Pridajte sa k nám na Patreone (otvorí sa v novej karte)](https://www.patreon.com/cw/roundly)

## 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.

[Ponuka do 48 hodín](https://roundly-consulting.com/sk/kontakt.md) [Prezrieť všetky balíky](https://roundly-consulting.com/sk/open-source/navody/webhooks-for-laravel.md)