Tajné kľúče a rotácia

• Vygenerované — whsec_ + štandardné base64 zo secrets.bytes (32) náhodných bajtov. Kľúčom HMAC sú dekódované bajty a prefix ich robí rozpoznateľnými pre skenery tajomstiev.
• Importované (prichádzajúce, create(secret: '…')) — uložené doslovne, 1–1 024 bajtov, bez riadiacich znakov. Ako sa z reťazca stanú bajty kľúča, určuje schéma. Pri predvolenej schéme musí byť kľúč whsec_… štandardné base64, ktoré sa dekóduje aspoň na jeden bajt, inak InvalidEndpointException; vlastné schémy (whsec_ v štýle Stripe použitý surovo) to nemusia spĺňať.
• V pokoji — šifrované cez encrypted cast Laravelu na secret aj previous_secret, oba skryté. Nikdy v resources, about, udalostiach, logoch ani správach výnimiek (všade #[SensitiveParameter]).
• Zobrazené raz — v CreatedInboundEndpoint, CreatedOutboundEndpoint a RotatedSecret; každý z nich sa skryje v print_r, var_dump aj json_encode.

Rotácia

$rotated = Webhooks::inbound()->rotateSecret($inboundEndpoint);                          // grace: secrets.grace_seconds (1 day)
$rotated = Webhooks::outbound()->rotateSecret($outboundEndpoint, grace: now()->addHours(6));
$rotated = Webhooks::inbound()->rotateSecret($inboundEndpoint, grace: now());            // no overlap
$rotated = Webhooks::inbound()->rotateSecret($inboundEndpoint, secret: $sendersNewSecret); // import (inbound)

$rotated->secret;       // the new secret, shown once
$rotated->graceEndsAt;  // when the old one stops working

• Aktuálny kľúč sa stane predchádzajúcim, nový aktuálnym a previous_secret_expires_at je koniec prechodného obdobia. Obdobie dlhšie ako secrets.max_grace_seconds (7 dní) alebo v minulosti vyhodí SecretRotationException.
• Ďalšia rotácia počas prechodného obdobia najstarší kľúč okamžite zahodí. Riadok sa uzamkne, takže dve súbežné rotácie zachovajú konzistentnú dvojicu. Vyvolá sa EndpointSecretRotated bez tajného kľúča.
• Pri prijímaní počas prechodného obdobia overujú oba kľúče a doručenie zaznamená, ktorý sa zhodoval (signature_slot current alebo previous). Pri odosielaní podpisujú oba — dve položky v1, nová prvá — takže príjemca prejde, kedy chce.
• Prechodné obdobie sa vynucuje pri použití; webhooks:prune vymaže predchádzajúce kľúče po jeho uplynutí.

php artisan webhooks:rotate-secret outbound 12 --grace=21600   # prints the new secret once

Zmazanie endpointu

delete() okamžite vymaže tajný kľúč aj predchádzajúci kľúč — pri odchádzajúcom endpointe aj URL a vlastné hlavičky. Zmazaný endpoint je mŕtvy; ručné obnovenie by si vyžadovalo nový kľúč cez rotateSecret(). Je to zámer: tajný kľúč zmazaného endpointu sa neuchováva roky. Riadok ostane v zázname, kým webhooks:prune neodstráni všetky doručenia, ktoré naň ukazujú.