NovinkaZverejnili sme 50+ Laravel balíkov ako open source
Custom AI apps, agents and automation — Roundly ConsultingRoundly
Všetky balíky

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ľúčEnvPredvolenéÚčel
key_typeWEBHOOKS_KEY_TYPEbigintbigint, uuid alebo ulid — typ kľúča modelov aplikácie, ktoré vlastnia endpointy (stĺpce morfu owner). Nastavte ho pred migráciou.
primary_key_typeWEBHOOKS_PRIMARY_KEY_TYPEbigintbigint, 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 modelsinbound_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—WebhookOwnerResourceAko sa vlastník endpointu vykreslí v JSON resources — inštancovateľná podtrieda JsonResource.

Front

KľúčEnvPredvolenéÚčel
queue.connectionWEBHOOKS_QUEUE_CONNECTIONblank = defaultSpojenie, ktoré používa každý job balíka.
queue.queueWEBHOOKS_QUEUE_NAMEblank = the connection’s defaultZáložný front pre oba smery.
queue.inboundWEBHOOKS_INBOUND_QUEUEblank = queue.queueFront pre ProcessInboundDelivery.
queue.outboundWEBHOOKS_OUTBOUND_QUEUEblank = queue.queueFront pre DeliverWebhook.
queue.max_delay—9001–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ľúčEnvPredvolenéÚčel
inbound.route.enabledWEBHOOKS_INBOUND_ROUTEonTrasa balíka POST {prefix}/{key}; vypnutá → pripojte si vlastnú.
inbound.route.prefix—webhooksPrefix trasy (lomky sa odstránia).
inbound.route.domain—nullDoména trasy.
inbound.route.middleware—[]Názvy middleware — nikdy web: odosielateľ nemá session ani CSRF token.
inbound.route.url_baseWEBHOOKS_INBOUND_URLnull = route()Základ URL adries endpointov, ktoré sa vám zobrazia ({url_base}/{key}), napríklad za proxy.
inbound.tolerance—3001–3 600 s — ako ďaleko od teraz môže byť podpísaná časová pečiatka, do minulosti aj budúcnosti.
inbound.max_payload_bytes—262144Limit veľkosti tela (256 KB), 1 – max_payload_bytes_ceiling.
inbound.max_payload_bytes_ceiling—10485761 – 67 108 864 — najviac, čo smie povoliť nastavenie konkrétneho endpointu (1 MB).
inbound.content_types—application/json, application/*+jsonPrijímané typy Content-Type (* je povolená v podtype, parametre sa ignorujú).
inbound.on_duplicate—acceptaccept odpovie na opakovanie 200 {"status":"duplicate"}; conflict odpovie 409.
inbound.accept_idempotency_header—onPoužiť Idempotency-Key, keď schéma nenesie id doručenia.
inbound.dedupe_ttl—60480060 – 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—600Overené doručenia na endpoint za minútu.
inbound.rate_limit.rejected_per_minute—60Odmietnuté požiadavky na endpoint a IP klienta za minútu.
inbound.rate_limit.cache_store—null = default storeCache úložisko limitérov — musí byť zdieľané, nikdy array.
inbound.store_headers—content-type, user-agent, webhook-id, webhook-timestampHlavičky uložené s doručením; podpisové, prihlasovacie a cookie hlavičky sa vynechajú bez ohľadu na zoznam.
inbound.requeue_after—60Uložené doručenie, ktoré sa po tomto počte sekúnd nedostalo do frontu, zaradí pravidelný beh.
inbound.handler.tries—31–100 — ProcessInboundDelivery::$tries.
inbound.handler.backoff—[10, 60, 300]Sekundy medzi pokusmi spracovania (zoznam alebo reťazec oddelený čiarkami).
inbound.handler.timeout—601–86 400 s — časový limit jobu spracovania.

Odosielanie

KľúčEnvPredvolenéÚčel
outbound.allow_httpWEBHOOKS_ALLOW_HTTPoffOkrem https aj http — len pre lokálny vývoj.
outbound.verify_on_save—onPreložiť a overiť URL pri vytvorení a úprave; vypnuté = všetky pravidlá okrem prekladu DNS.
outbound.envelope—onZabaliť 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—262144Limit zakódovaného tela (PayloadTooLargeException).
outbound.max_response_bytes—40961 – 1 048 576 — koľko z odpovede príjemcu sa prečíta a uloží.
outbound.timeouts.connect—51–60 s — limit na pripojenie.
outbound.timeouts.total—10connect – 300 s — jeden rozpočet pre všetky kroky presmerovania; DeliverWebhook::$timeout je táto hodnota + 20.
outbound.max_attempts—81–25 pokusov na sériu doručenia.
outbound.retry.base—60delay(n) = min(base · multiplier^(n-1), cap).
outbound.retry.multiplier—41–100.
outbound.retry.cap—32400Najdlhšie vypočítané oneskorenie (9 h).
outbound.retry.jitter_permille—1000–500 — náhodný rozptyl (± 10 %).
outbound.retry.max_retry_after—86400Najdlhší rešpektovaný Retry-After.
outbound.retry.schedule—nullExplicitné oneskorenia namiesto vzorca ([60, 300, 3600]); za koncom sa opakuje posledná hodnota.
outbound.rate_limit.per_minute—60Požiadavky na endpoint za minútu (endpoint môže prepísať).
outbound.requeue_after—120Splatné 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—10001 – 100 000 — najviac jobov odosielania, ktoré odošle jeden beh webhooks:retry.
outbound.disable_after—5Počet doručení po sebe, ktoré skončili ako failed, kým sa endpoint vypne.
outbound.disable_on_gone—onOdpoveď 410 Gone endpoint okamžite vypne.
outbound.follow_redirects—offSledovať 307/308 (každý krok sa znova overí).
outbound.max_redirects—30–10.
outbound.headers.allowed_overrides—[]Rezervované vlastné hlavičky, ktoré endpoint smie nastaviť: host (len pri vypnutom ssrf.enabled), authorization.
outbound.user_agentWEBHOOKS_USER_AGENTblank = "{app.name} Webhooks"User-Agent, ktorý vidia príjemcovia (Laravel Webhooks, ak aplikácia nemá názov).

Bezpečnosť odosielania (SSRF)

KľúčEnvPredvolenéÚčel
ssrf.enabledWEBHOOKS_SSRF_GUARDonOchrana; vypnúť len za filtrujúcou výstupnou proxy, ktorej dôverujete.
ssrf.block_app_hosts—onOdmietnuť 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 = anyZoznam portov 1–65 535.

Tajné kľúče, schémy a handlery

KľúčEnvPredvolenéÚčel
secrets.bytes—3224–64 náhodných bajtov vo vygenerovanom tajnom kľúči (whsec_ + base64).
secrets.grace_seconds—86400Predvolené prechodné obdobie vyradeného tajného kľúča, 0 – max_grace_seconds.
secrets.max_grace_seconds—604800Najdlhšie prechodné obdobie, ktoré rotateSecret() prijme (0 – 31 536 000).
schemes—default ⇒ DefaultScheme, rfc9421 ⇒ Rfc9421SchemeNázov ⇒ trieda SignatureScheme; vlastné pridajte tu alebo cez Webhooks::schemes()->extend().
rfc9421.profile—defaultPodpisový profil Sentinelu, voči ktorému overujú prichádzajúce endpointy RFC 9421 (scheme_options.profile endpointu má prednosť).
rfc9421.outbound_key_id—nullKľúč 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ľúčEnvPredvolenéÚčel
sanitizer.class—KeyRedactingSanitizerTrieda 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, ssnNá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—301–36 500 — obsah, telá a výňatky odpovedí sa potom vymažú.
payloads.delivery_retention_days—901–36 500 alebo null = ponechať — riadky doručení a pokusov (a zmazané endpointy, na ktoré nič neukazuje) sa potom zmažú.
schedule.enabled—onProvider naplánuje webhooks:retry a webhooks:prune.
schedule.retry—everyMinuteeveryMinute, everyTwoMinutes alebo everyFiveMinutes.
schedule.prune—dailyhourly, 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):

NastavenieInboundEndpointOptionsOutboundEndpointOptions
Limit za minúturateLimitPerMinuterateLimitPerMinute
Veľkosť telamaxPayloadBytes—
Typy obsahucontentTypes—
Tolerancia časovej pečiatkytoleranceSeconds—
Voľby schémyschemeOptions (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=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

Odoslaní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.