Security
Webhook URLs are attacker-influenced, so every endpoint is validated when it is registered and again immediately before each delivery, with the connection pinned to the validated IP so a rebinding DNS record cannot redirect it.
Private, loopback, link-local, unique-local, carrier-grade-NAT, multicast and cloud-metadata
(169.254.169.254) addresses are refused, redirects are not followed, and TLS verification
stays on.
The IPv6 transition prefixes are refused too — 6to4 (2002::/16), its deprecated relay
anycast (192.88.99.0/24), Teredo (2001::/32) and both ORCHID blocks. Those matter more
than their obscurity suggests: 6to4 and Teredo embed an IPv4 address, and not in the low
bits where an IPv4-mapped address carries it. 2002:7f00:1:: is 127.0.0.1 wearing a
different encoding, and an unwrapper that only knows the mapped, translated and compatible
forms walks straight past it.
Beyond those, every block the IANA special-purpose address registries list as not globally
reachable is refused, among them the segment routing identifiers an operator routes inside its
own network (5f00::/16) and the dummy prefix (100:0:0:1::/64). The IETF protocol assignments
block 2001::/23 is refused whole, like its IPv4 counterpart 192.0.0.0/24: the few addresses
in it that IANA does call reachable are anycast services, relays and sinks, not webhook
receivers.
IPv6 outside the global unicast space 2000::/3 is refused as a whole, because IANA assigns
routable IPv6 from that block only and keeps the rest reserved. An IPv6 literal that embeds an
IPv4 address is judged as that IPv4 address.
Signing secrets are stored encrypted at rest; inbound sensitive headers (Authorization,
Cookie, plus your redact list) are masked before storage.
core.ssrf.allowed_hosts is an opt-out, not an allowlist
A host you put on it skips DNS resolution, skips the private/loopback/metadata IP classification and skips the IP pin — so that host may resolve into your internal network and its DNS record may rebind between the check and the connection.
Use it only for a known internal endpoint whose risk you accept. The restrictive list is
core.ssrf.blocked_hosts. An IP address on it is refused however a URL spells it (decimal,
IPv4-mapped IPv6, uncompressed IPv6) and whatever name resolves to it; a name on it blocks that
name, not another name for the same server. And core.ssrf.block_private_networks = false
switches the guard off globally — leave it true.
The IP pin does not survive a proxy
The SSRF guard vets and pins a destination IP for direct connections. A forward proxy
resolves the hostname itself, so the pin is not enforced through it and the anti-rebinding
guarantee becomes the proxy's responsibility — your proxy must enforce its own egress control.
Leave core.egress.proxy unset unless the proxy does that.
Unset means direct. A proxy named in the worker's environment (HTTPS_PROXY, or HTTP_PROXY
on the command line a queue worker runs on) is bypassed for deliveries and JWKS fetches, so it
cannot carry them around the pin without anyone having configured it.
Fetching an outside URL under the same guard
Core\Http\GuardedFetch gets a URL your application did not choose, an image in a received mail
or a document a user linked to, with the guarantees a delivery has: the URL is vetted and the
connection pinned to the vetted addresses, a redirect is handed back rather than followed, a proxy
in the environment is bypassed, a compressed body is never inflated, and TLS stays verified.
use Pushery\Webhooks\Core\Http\Exceptions\BlockedDestination;
use Pushery\Webhooks\Core\Http\Exceptions\ResponseTooLarge;
use Pushery\Webhooks\Core\Http\GuardedFetch;
try {
$image = app(GuardedFetch::class)->get($url, maxBytes: 5_000_000, headers: ['Accept' => 'image/*']);
} catch (BlockedDestination|ResponseTooLarge) {
return null; // a private address, or a body past the limit
}
$image->status; // 200, or a 3xx whose Location you may vet and fetch in turn
$image->header('Content-Type'); // the first value, the name matched in any case
$image->body; // at most 5 000 000 bytes
The body is held to maxBytes. A response that declares a longer length is refused before its
first byte, and one that sends without a length is cut off where it passes the limit, so a server
that never stops sending costs the limit and not the timeout. Either way the fetch throws
ResponseTooLarge and hands nothing of the body back. The same limit holds for a response faked
with Http::fake(). connectTimeout and timeout default to 3 and 10 seconds.
Some files are read only up to a point: Google applies the rules in the first 500 KiB of a
robots.txt and ignores what follows. truncate: true asks the fetch for that head instead of
the refusal:
$robots = app(GuardedFetch::class)->get('https://shop.example/robots.txt', maxBytes: 512_000, truncate: true);
$robots->body; // at most 512,000 bytes
$robots->truncated; // true where the file was longer and is cut at the limit
The transfer still ends at the limit, and the status and the headers are those of the response. A
declared length past the limit is read up to the limit rather than refused before its first byte.
Without the option nothing changes, and a longer body throws ResponseTooLarge.
A timeout that strikes after the server accepted the connection, with no answer within timeout
or one that had not ended by then, throws ResponseTimedOut. It is a ConnectionException, so a
catch of that still takes it, and a caller that reads many URLs on one server can catch it first
and go on to the next URL: a connection that is refused or not made within connectTimeout stays a
plain ConnectionException, and may mean the server is gone. lead() and follow() answer the
same way.
The fetch asks the guard the delivery uses, so core.ssrf decides for both: with https_only,
get() refuses a plain http:// URL, and a host on allowed_hosts is fetched unpinned.
Where a URL leads
lead() asks a URL only for its status and its headers. The request is a GET, and the transfer
ends as soon as the headers are in, so the body is never read: a page of any length, or one that
never ends, costs neither the status nor the time.
use Pushery\Webhooks\Core\Http\GuardedFetch;
$answer = app(GuardedFetch::class)->lead('http://shop.example/');
$answer->status; // 301
$answer->header('Location'); // https://shop.example/
$answer->body; // always empty
Everything else holds as for get(): the URL is vetted and the connection pinned, a redirect is
handed back, a proxy in the environment is bypassed, nothing is inflated, and TLS stays verified.
A plaintext http:// URL is taken even with https_only on, because that switch holds what a
webhook carries and a lead carries nothing. The guard vets the URL in its https form, which
stands at the same addresses, and the connection is pinned to them on the port of the plaintext
URL. An informational answer such as 103 Early Hints is passed over for the response it
precedes.
Following a chain of redirects
follow() goes where a URL leads, station by station, and hands back the whole chain. Each
redirect target is resolved against the URL that answered, a relative and a protocol-relative one
included, and then vetted and pinned as the first URL was:
use Pushery\Webhooks\Core\Http\GuardedFetch;
use Pushery\Webhooks\Core\Http\RedirectScope;
$chain = app(GuardedFetch::class)->follow('http://shop.example/', maxRedirects: 5, scope: RedirectScope::SameDomain, allowDowngrade: false);
$chain->finalUrl(); // https://www.shop.example/
$chain->response->status; // 200
$chain->hops; // every station, with its URL, status, Location and duration
$chain->stoppedBecause; // null, or why the chain ended at a redirect
$chain->notFollowed; // the target of that redirect
Without maxBytes each station is asked like lead(), reading no body and taking a plaintext URL;
with it, like get() under that limit, so the last response carries its body. With truncate: true
as well, a longer body at any station is cut to the limit instead of refused, so a chain read only
for where it leads, a sitemap that moved for one, can name a small limit and still gets every
status and Location. Every station is a GET, which a 303 asks for and a 307 or a 308 keeps.
The chain ends at a redirect instead of following it, and says why in stoppedBecause, when the
target is no http or https URL (InvalidTarget), steps down from https to http without
allowDowngrade (Downgrade), lies outside the scope (OutOfScope), was reached before (Loop),
would pass maxRedirects (TooManyRedirects), or is refused by the guard or resolves to nothing
(Refused, Unresolvable). The first URL is the exception: refused, it throws as get() and
lead() do. RedirectScope::SameHost keeps the chain on the first host, as a proof of a site's
ownership needs; SameDomain lets it reach the same name with or without www. and its
subdomains, never a name above it.
Classifying an address without fetching it
Core\Ssrf\AddressClassifier is the range list the guard vets every address against, and an
application asks it the same way about an address it holds, such as the literal target of a link
it stores:
use Pushery\Webhooks\Core\Ssrf\AddressClassifier;
$classifier = app(AddressClassifier::class);
$classifier->isBlocked('100.64.0.1'); // true: carrier-grade NAT
$classifier->isBlocked('::7f00:1'); // true: 127.0.0.1 in the IPv4-compatible form
$classifier->isBlocked('93.184.216.34'); // false
$classifier->isBlocked('shop.example'); // true: a name is not an address
$classifier->canonical('::ffff:127.0.0.1'); // 127.0.0.1
$classifier->canonical('[2001:DB8::1]'); // 2001:db8::1
$classifier->canonical('shop.example'); // null
It resolves nothing and reads no configuration. https_only, allowed_hosts and
block_private_networks decide what the guard lets through and leave the classifier's answer as
it is, so an http:// link is judged by its address alone. Anything that is not an IP address
counts as blocked, a host name among them; an IPv6 address is passed without the brackets a URL
puts around it, which canonical() removes.
PHP's filter_var() with FILTER_FLAG_NO_PRIV_RANGE | FILTER_FLAG_NO_RES_RANGE is no substitute.
On PHP 8.5 it passes carrier-grade NAT, benchmarking, site-local IPv6, the transition prefixes,
the documentation blocks and multicast as public, and it passes ::7f00:1 while it refuses
::127.0.0.1, which is the same address.
A signing secret does not leave the model by accident
WebhookSubscription casts secret and previous_secret as encrypted, which protects them
in the database. It does not protect the way out: Eloquent decrypts a cast attribute on the
way into toArray(), so a serialized model used to carry the plaintext whsec_….
Both are now on the model's $hidden list. toArray(), toJson() and (string) $model —
which is what Log::info($subscription) writes — no longer contain them.
Reading the secret still works exactly as the guides describe, because $hidden governs
serialization and not property access:
$subscription->secret; // the plaintext, once
Worth knowing if you listen for WebhookEndpointRegistered to write an audit trail: that event
carries the model, and serializing it there was the realistic way this leaked.
A queued delivery keeps its body out of the queue
A delivery waits in the queue with everything it sends, its body included, and the body is where
a sender's personal data travels: a name, an address, a bank account. With
webhooks.server.encrypt_jobs, which is on unless you switch it off, Laravel encrypts the whole
job with APP_KEY while it waits, through every retry and in failed_jobs once it gives up, so
neither Redis nor the jobs table holds a byte of the body in the clear. A queue worker needs the
same APP_KEY as the application that sends, which opening the signing secret already asked of
it. A job queued before the switch existed is still read.
WEBHOOKS_SERVER_ENCRYPT_JOBS=false writes the job as before. Two copies of the body stay outside
the switch:
- A listener of an attempt event (
WebhookAttemptStartingand the others) that implementsShouldQueuewrites the event, with the delivery and its body, into a job of its own. Give such a listenerShouldBeEncryptedas well. - The delivery log of
server.persistence, when you switch it on, keeps the body in your database, andserver.large_payloadmoves a large one to its disk.
Rotating APP_KEY
The endpoint secrets and the entries waiting in the transactional outbox are encrypted with
APP_KEY. After a rotation Laravel still decrypts them with a key listed in
APP_PREVIOUS_KEYS, but it encrypts under the new key only what it writes, and an endpoint's
secret is written again only when the endpoint rotates it. Until then the old key cannot leave
APP_PREVIOUS_KEYS: without it, every endpoint that has not rotated since can no longer sign,
and an outbox entry can no longer be sent.
php artisan webhooks:reencrypt writes those values again under the current key:
- Set the new
APP_KEY, move the old one toAPP_PREVIOUS_KEYS, and deploy. - Run
php artisan webhooks:reencrypt. It reads each endpoint and each outbox entry again under a lock, so a secret rotated at the same moment is not overwritten, and it leavesupdated_atas it was. A value that no configured key decrypts is named with its row, and the command exits with 1. - Wait until the deliveries queued before the deploy have been sent. A queued delivery is sealed
under the key it was queued with, the whole job where
server.encrypt_jobsis on and the values it signs and connects with in any case, and the queue is out of the command's reach. The same holds for a failed webhook job you may still retry. - Run the command again. Once it encrypts nothing more, remove the old key from
APP_PREVIOUS_KEYS.
php artisan webhooks:reencrypt --dry-run answers the same question without writing: it decrypts
every value, reports how many a run would encrypt again, and exits with 1 for a value no
configured key opens, which is the check to make before a key leaves APP_PREVIOUS_KEYS.
A host with a database per tenant runs the command inside its tenant loop, the way it runs the scheduled ones. The command covers what this package stores; encrypted columns of your own models need the same step.
Turning on search sends data out of the application
The delivery body is governed everywhere else by the view-webhook-payload ability: without
it, a reader sees the shape ([string], [int]) rather than the customer's email, and that
decision is made per request, against the person looking.
An index has neither a request nor a person. It is one shared artifact, queried by
everyone who can query it, held by a service whose retention, backups and access control are
not this application's. So the ability cannot govern it, and the package does not pretend it
can: with webhooks.search.enabled on, the index carries the event type, the url, the
status, the owner pair and the timestamp — everything a search needs — and not the body.
Copying the body in is a separate, explicit decision:
// config/webhooks.php
'search' => [
'enabled' => true,
'index_payload' => true, // off unless you set it
],
Turn it on only where the index is protected as well as the database it mirrors. What lands
there is the first payload_excerpt_chars characters of the payload verbatim — not redacted,
whatever the ability says on screen.
A payload that was offloaded to a Storage disk is never read back for indexing, so a large body is not copied into the index either way.
Reporting a vulnerability
Report vulnerabilities privately, per the security policy.