Laravel Config Webhook Laravel Package

Getting Started

1. composer require cleaniquecoders/laravel-config-webhook
2. Publish the package config (and migrations, if you persist delivery records): php artisan vendor:publish --provider="CleaniqueCoders\ConfigWebhook\..." — check the README for the exact tag name; the config file is where endpoints and the signing secret live.
3. Add the secret to .env and never commit it; on the receiving side verify the signature against the raw request body.
4. First use case: register a single endpoint in config for a low-risk event (e.g. order.created), dispatch it from a queued listener, and confirm on the receiver that hash_hmac('sha256', $request->getContent(), $secret) matches the signature header.

Where to look first, in order: the published config file (it is the source of truth for endpoints, secret, retries, and the new allow_private_hosts flag), then the delivery/failed-record model so you know what "failed" looks like in the DB, then the README's receiver-verification snippet.

Implementation Patterns

Config-as-code endpoints. Define endpoints per environment in config/…webhook.php and override hosts/secrets via env. Treat the config file as deployable infrastructure — review changes to it like you review routes.

Receiver verification (the important one in 1.1.0). Verify against the exact bytes received:

$raw = $request->getContent();               // NOT $request->all()
$expected = hash_hmac('sha256', $raw, $secret);
abort_unless(hash_equals($expected, (string) $request->header('X-Signature')), 401);

Then json_decode($raw, true). Never re-encode before verifying — re-encoding changes key order, spacing, unicode escaping, and float formatting.

Fan-out per event. Register multiple endpoints for one event type and dispatch once; keep each endpoint's secret distinct so a leak is scoped to one consumer.

Asynchronous delivery + idempotency. Dispatch from queued listeners/jobs, and include a stable delivery/event ID header so receivers can dedupe on retries. Store the delivery record's ID alongside your domain event so support can trace a single webhook end-to-end.

Failed-delivery handling as a first-class workflow. Since blocked hosts are marked failed with no retry, your monitoring must distinguish "refused by policy" from "network/5xx error" — otherwise a misconfigured internal endpoint looks like an outage. Add an alert or a scheduled command that surfaces newly failed deliveries grouped by failure reason.

Testing. Use Http::fake() and Http::assertSent() to assert the outgoing body byte-for-byte and the signature header. Add one test that asserts a 127.0.0.1 endpoint is refused with allow_private_hosts false, and one that asserts it is allowed when true.

Local development. Set CONFIG_WEBHOOK_ALLOW_PRIVATE_HOSTS=true in .env.local / .env.testing only, when pointing at a receiver on http://localhost or a Docker service name.

Gotchas and Tips

Upgrading to 1.1.0 is effectively a breaking change for some installs. Any existing webhook pointing at a private, loopback, link-local, or reserved address immediately stops delivering, is marked failed, and is not retried. Before upgrading, audit your endpoint config and delivery table for internal targets (10/8, 172.16/12, 192.168/16, 127.0.0.0/8, ::1, 169.254.169.254, *.internal, *.local, Kubernetes service names). Either migrate those to a publicly resolvable address or explicitly set allow_private_hosts — and document why.

Never enable allow_private_hosts in production. This flag disables SSRF protection, including cloud metadata access. Guard it at the environment level, not with application logic: keep it out of .env.example defaulting to true, and consider a deploy-time assertion that it is false when app()->isProduction().

Redirects are not followed. An endpoint that 301/302s to a canonical URL (http→https, apex→www, a load balancer's redirect) will now fail. Point config directly at the final URL.

DNS pinning changes failover semantics. The hostname is resolved once, checked, and the connection is pinned to that IP. Any middleware or proxy that rewrites the request body on the receiving side invalidates the signature — that's a receiver problem, but it will look like a sender problem.

Signature verification failures are usually body-handling bugs on the receiver, not sender bugs. In Laravel the usual causes are verifying $request->all() instead of getContent(), a middleware calling $request->json(), or an upstream proxy normalizing the payload. Log the raw body hash on both sides when debugging.

Debugging a refused host: check the delivery record's failure reason first, then resolve the hostname yourself (dig +short) to see which IP was classified as private — a CNAME pointing at an internal name is easy to miss.

Extension points to prefer: the published config for endpoints/secrets/retry policy, package events for delivery success/failure (hook your monitoring there rather than polling the table), and wrapping dispatch in your own job if you need per-tenant rate limiting or ordering guarantees the package doesn't provide.