Laravel Webhook Client Laravel Package

Technical Evaluation

Architecture fit. This is a narrow, opinionated inbound-webhook component rather than a webhook platform. It implements one pipeline: signature validation → profile filter → persist to webhook_calls → dispatch queued job → HTTP response. That maps cleanly onto any "third party calls us about an event" integration, and it deliberately enforces the right shape (fast 200, async processing, payload stored before processing) rather than leaving it to each team to get wrong. Fit is high if the receiving service is already Laravel with a working queue fleet. Fit is poor if we want a single polyglot webhook gateway: Route::webhooks, the Eloquent WebhookCall model, the config file, and the container-bound extension points make it Laravel-coupled by design.

Integration feasibility. Low effort, high leverage. Installation is three Artisan commands plus config, one route, and one job class. The extension seams — SignatureValidator, WebhookProfile, WebhookResponse, custom WebhookCall model, ProcessWebhookJob — cover most real customization without forking. Rough sizing: one to two developer-days for a first endpoint; per-provider validator work thereafter.

Technical risk.

• The default signature validator is HMAC-SHA256 over the raw body only, with no timestamp or nonce. That means no replay protection and no tolerance window. Any provider signing with a timestamped scheme needs a custom validator; so do providers whose signature format differs (base64 HMAC, sha256= prefix, form-encoded bodies). The default should be treated as a template, not a solution.
• Invalid signatures return 500 and fire InvalidWebhookSignatureEvent. 500 is retryable for most senders, so a rotated or misconfigured secret becomes a retry storm rather than a clean drop. Decide this intentionally.
• CSRF exclusion is manual and easy to forget; a missed exclusion yields 419 and no stored payload.
• No built-in idempotency or dedup key. The WebhookProfile hook is the only pre-persist interception point, so dedup must be custom-built.
• No rate limiting, IP allow-listing, or payload size cap out of the box — must be layered via middleware.
• No replay or dead-letter tooling. Retries are whatever Laravel queue semantics provide; failed jobs land in failed_jobs with no first-class reprocessing path.
• Metadata anomalies to verify before committing: "Dependents: 0" is implausible for a package with this download profile (likely a scraping gap), and the last release date of 2026-07-28 is in the future. Confirm the actual version and framework compatibility matrix on Packagist rather than trusting the summary.
• Single-vendor open-source dependency with no commercial SLA for this package.

Key questions. Which providers, and what are their exact signing schemes? Peak and burst request volume? What idempotency guarantees does each event type need? What PII or retention constraints apply to stored payloads and headers? Do we need replay? Which queue driver and worker SLA? Which Laravel and PHP versions are in the estate? Is multi-tenant isolation required at the endpoint, secret, or storage layer?

Integration Approach

Stack fit. Native for a Laravel service: works against MySQL/Postgres (JSON payload column), any Laravel queue backend (Redis, SQS, database), and Horizon for visibility. Does not fit if intake is standardized outside PHP — adopting it there would make one service's webhook handling inconsistent with the rest.

Migration path. If teams currently hand-roll webhook controllers, migrate one provider at a time. Stand the new endpoint up alongside the old one behind a flag, dual-deliver for a short window, and diff persisted payloads against the legacy path before cutting over. This is the cheapest way to prove validator correctness against real traffic.

Compatibility. Pin to a release whose Laravel and PHP constraints match our estate, and whose published migration fits our migration conventions (table naming, ID strategy, JSON column support on the target DB driver). Verify against our exact framework version, not just latest.

Sequencing.

1. Install; publish config and migration; validate in a non-production environment.
2. Implement a per-provider SignatureValidator — assume the default is insufficient until proven otherwise.
3. Implement WebhookProfile for dedup and event filtering.
4. Implement ProcessWebhookJob; keep it short, idempotent, and delegating to domain services rather than containing business logic.
5. Register the route, exclude CSRF, add throttling and any auth/IP middleware.
6. Add retention scheduling and observability (see below).
7. Only then add further endpoints via the configs array — multi-endpoint support is config-only and cheap once the first path is proven.

Operational Impact

Maintenance. Small code surface, real ongoing ownership. The config file is per-endpoint and will accumulate provider quirks. Every new provider means a validator, a job, and a config entry — budget incremental effort per integration, not a one-time cost. Spatie ships frequently; maintain a dependency-update cadence backed by tests that cover signature validation and job dispatch.

Support. Community only — GitHub issues, no SLA. If webhook intake is revenue-critical, that gap must be absorbed internally: a named owner, documented signing schemes per provider, and a runbook for "webhooks are failing."

Scaling. Ingest itself is cheap — validate, insert, dispatch, return 200. The bottleneck is the worker pool, not the endpoint. Persisted volume is the real cost driver: every call is a row, plus full payload, plus headers if store_headers is *. The default delete_after_days of 30 caps growth, but retention trades off against replay and audit needs and should be an explicit decision. At high volume, plan indexing discipline on webhook_calls and consider a dedicated connection.

Failure modes. None of these are alerted by default:

• Rotated/mismatched secret → 500 → sender retries → no data stored.
• Missing CSRF exclusion → 419, nothing persisted.
• Queue unavailable → exception recorded on the WebhookCall, request still returns 200 → silent loss.
• Job throws → lands in failed_jobs, no automatic replay.
• Worker backlog → 200s keep flowing while processing lags unboundedly, with no backpressure signal.
• Duplicate delivery (normal for most providers) → duplicate domain effects absent custom dedup.
• Replay of a captured valid payload → accepted, since the signature carries no timestamp binding.

Each needs a deliberate monitoring decision before go-live.

Ramp-up. A mid-level Laravel developer can ship the first endpoint in a day from the README. The harder work — dedup, replay posture, retention, alerting — is exactly what the README does not cover, and where a TPM should set the definition of done. Recommended rollout: treat the first integration as a pilot with full observability, then templatize it (config snippet, validator base class, job scaffold, alert set) so subsequent providers are a repeatable pattern rather than a fresh design exercise.