Skip to main content

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 (WebhookAttemptStarting and the others) that implements ShouldQueue writes the event, with the delivery and its body, into a job of its own. Give such a listener ShouldBeEncrypted as well.
  • The delivery log of server.persistence, when you switch it on, keeps the body in your database, and server.large_payload moves 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:

  1. Set the new APP_KEY, move the old one to APP_PREVIOUS_KEYS, and deploy.
  2. 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 leaves updated_at as it was. A value that no configured key decrypts is named with its row, and the command exits with 1.
  3. 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_jobs is 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.
  4. 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.