Laravel Config Webhook Laravel Package

Technical Evaluation

Architecture fit laravel-config-webhook is a small, single-purpose outbound webhook dispatcher for Laravel: webhook endpoints and payloads are driven from configuration, requests are signed, and delivery goes through the framework's HTTP client. Release 1.1.0 shifts the package from "convenience dispatcher" to "hardened dispatcher" by closing an SSRF class of vulnerability and fixing a signature-correctness defect. For most Laravel services this is a clean fit: it sits in the same layer as Http::post(), requires no new infrastructure, and inherits Laravel's queue, events, and logging. It is not a full webhook platform — it does not appear to provide subscriber management, delivery dashboards, replay tooling, or per-endpoint secret rotation. Teams expecting those capabilities should treat it as a transport primitive and plan to build the surrounding control plane, or evaluate a heavier alternative.

Integration feasibility Low-to-moderate effort. Installation is Composer-only, configuration is a published config file plus environment variables (CONFIG_WEBHOOK_ALLOW_PRIVATE_HOSTS is the new one), and the signing contract is now stable and verifiable because the body is sent as the exact signed JSON string. That last fix is the one that matters most for integration: previously, re-encoding could invalidate HMAC signatures on the receiver side, which is the classic cause of intermittent, hard-to-reproduce 401s in webhook integrations. Any receiver that validates signatures should now work reliably. The main integration work is inventory: enumerating every configured endpoint and confirming each resolves to a public address.

Technical risk

• Breaking behaviour change in a minor version. Existing webhooks pointing at private, loopback, link-local, or reserved addresses are now refused at save and at send, marked failed with no retry. This is correct security posture but is a semantic break published as 1.1.0. Any environment that legitimately delivers to an internal service (sidecar, VPC-internal consumer, Docker hostname, *.internal, 169.254.169.254-adjacent tooling) will silently stop delivering on upgrade. This is the highest-impact item in the release.
• DNS pinning and redirect refusal are strong SSRF controls but introduce compatibility edges: endpoints behind rotating DNS, CDNs that rely on 3xx to a canonical host, or egress through a proxy that resolves names itself may fail. The failure will present as a delivery error, not as a security block, so misdiagnosis is likely.
• The allowlist flag is a footgun if overused. allow_private_hosts=true re-opens the entire SSRF surface globally rather than per-endpoint. It must be dev/test-only and enforced as such in CI and config review.
• Unknowns: no evidence in the notes about retry/backoff semantics, dead-letter handling, timeout configuration, or how "marked failed" is persisted and surfaced. Those determine blast radius when deliveries fail.

Key questions

1. Is the private-host check applied at config save, at dispatch, or both — and does a failed check surface as a validation error, a queued job failure, or a silent skip?
2. How is "marked failed, no retry" recorded? Is there an event, log channel, or table a TPM/on-call can query?
3. Does DNS pinning honour HTTP_PROXY/HTTPS_PROXY and custom Guzzle handlers, or does it bypass them?
4. What is the signature scheme (algorithm, header name, timestamp/nonce, replay window) and is it documented well enough for third-party receivers to implement?
5. Is per-endpoint configuration supported (secrets, headers, timeouts), or is it global-only?
6. Does the package dispatch synchronously or require a queue worker, and what happens on worker backlog?

Integration Approach

Stack fit Requires Laravel with the HTTP client and, if asynchronous, a queue backend. No database assumption beyond whatever backs the webhook configuration source; no additional services. Fits existing Laravel monoliths and API services with minimal footprint, and composes with Horizon, Telescope, and the standard logging stack.

Migration path Treat 1.0.1 → 1.1.0 as a behaviour-breaking upgrade despite the minor version number.

1. Freeze and export the current webhook endpoint inventory (config file, env, and any persisted records).
2. Resolve every hostname to IPs and classify public vs. private/loopback/link-local/reserved, including IPv6 and DNS names that resolve internally.
3. For each internal endpoint, decide: migrate the consumer to a public ingress, replace the package with a direct Http call in that specific code path, or (dev/test only) set CONFIG_WEBHOOK_ALLOW_PRIVATE_HOSTS=true.
4. Upgrade in staging first with delivery assertions against a signature-validating receiver, confirming the raw-body fix.
5. Roll to production behind a flag or during a low-traffic window, with delivery success rate monitored for 24–48 hours.

Compatibility The raw-body signing change is backward compatible for receivers that validate against the received bytes and fixes receivers that were failing; receivers that (incorrectly) parsed and re-serialised before verifying may need review. The private-host block is the only true incompatibility. allow_private_hosts defaults to false, so behaviour changes on upgrade without any config edit — there is no opt-in grace period.

Sequencing (1) inventory and classify endpoints, (2) decide per-endpoint disposition for internal targets, (3) staging upgrade with signature verification and delivery tests, (4) add delivery-failure alerting if not already present, (5) production rollout, (6) post-rollout audit confirming zero unexpected failed deliveries, (7) codify a config-review rule that allow_private_hosts=true cannot reach production.

Operational Impact

Maintenance Low code footprint, but the package now owns a security-relevant control (egress validation), which raises the maintenance bar: pin the version, subscribe to advisories, and expect further hardening releases. The signature-format fix means receivers should be re-validated once and then left alone. Budget a small ongoing task for keeping the endpoint inventory accurate — stale entries are the main source of surprise failures.

Support Failure diagnosis is the weak point. A blocked private host, a redirect refusal, a DNS-pinning mismatch, and a receiver-side signature rejection can all look like "webhook didn't arrive." Support runbooks must distinguish them: capture the resolved IP, the block reason, and the outbound body/headers for at least the last N attempts. Without a persisted delivery record, on-call will be dependent on application logs.

Scaling Outbound volume scales with the queue worker pool, not the package; no shared state or locking is implied. The DNS-pinning check adds a resolution step per send — negligible individually, but if endpoints are numerous and delivery is synchronous, it becomes a latency contributor and a partial failure point. Prefer queued dispatch with per-endpoint timeouts and bounded concurrency, and watch for head-of-line blocking during a slow receiver.

Failure modes

• Internal/private endpoint after upgrade → hard fail, no retry, no automatic recovery. Highest-likelihood incident.
• Receiver behind redirect → blocked by design; delivery never completes.
• Endpoint IP changes to a private range (DNS rebinding or a genuine migration) → previously working endpoint starts failing without a config change.
• Signature verification failure at the receiver if it re-serialises the payload — resolved by 1.1.0, but receivers built against 1.0.1 assumptions may need updating.
• allow_private_hosts=true leaking to production → silent loss of SSRF protection; no runtime symptom until exploited.
• Queue backlog or worker starvation → delayed but not lost deliveries; needs lag monitoring.

Ramp-up A Laravel developer can integrate the package in under a day. The real ramp-up is on the operational side: understanding the egress policy, the signature contract, and the failure taxonomy — roughly 2–3 days for the engineer owning the integration and half a day for on-call to absorb the runbook. Plan a short internal note documenting the private-host policy and the exact procedure for adding a new endpoint, since that is now a security-reviewed change rather than a config edit.