Webhook Laravel Package

Product Decisions This Supports

• Build vs. buy on webhook plumbing: The component gives you two reusable primitives — inbound RequestParserInterface implementations (with signature verification and payload normalization) and outbound transports/endpoints — that would otherwise be bespoke code in every integration. A PM decision to "standardize webhook handling" rather than "write per-provider handlers" is exactly what this package supports. Note this is a Symfony component consumed inside Laravel, not a Laravel package: Illuminate\Http\Request extends Symfony\Component\HttpFoundation\Request, so the bridge is real but must be documented once by us.

• Roadmap sequencing for event-driven features: If the roadmap contains "real-time order updates," "payment status sync," or "marketplace event bus," this component front-loads the commodity work (HMAC verification, payload parsing, retry-aware delivery) so engineering time lands on business logic. That can move a first integration from a multi-sprint effort to a spike plus a parser class — for a single, well-understood provider (Stripe, GitHub, Slack).

• Scope discipline on in-house webhook infrastructure: Choosing this explicitly says "we will not own a webhook framework." That is a defensible product bet because the component is maintained in lockstep with Symfony (it ships as part of the symfony/symfony monorepo, split out for standalone install), so security fixes arrive on Symfony's release cadence rather than ours. The trade-off is that we adopt Symfony's abstractions and versioning policy.

• Use cases that fit well: inbound signature-verified receivers for a known set of providers; internal service-to-service event notifications where both ends are ours (so payload schema is under our control); fan-out of domain events to customer-configured endpoints where a transport abstraction pays for itself once there are 3+ endpoint types; and Messenger-queued consumption, which maps cleanly onto Laravel queues/Horizon.

• Use cases that do not differentiate: one-off webhook receivers (a controller with hash_hmac is ~20 lines and cheaper to own), high-volume ingestion needing per-tenant rate limiting or replay windows, or anything requiring provider-specific verification schemes that no existing parser covers — you would be writing the parser anyway, so the component only saves you the dispatch scaffolding.

• Decision-grade caveat on the adoption signal: 56 stars and 0 listed dependents reflect a split-repository artifact, not real usage — most consumers install symfony/webhook transitively or use the monorepo, and the dependency graph does not capture that. Do not read this as low adoption; also do not read Symfony's brand as proof of fit for Laravel. The honest signal is: mature release history (6.3 → 8.1), thin README, documentation hosted externally, and changelogs that are mostly "no significant changes" (expected for a stable component). Treat the 2026-09-15 release date as a metadata artifact and verify the real pin during the spike.

• Explicit non-goal: this is not a webhook product (no delivery dashboard, no replay UI, no per-endpoint observability, no secret rotation UX). If the roadmap promises customers "manage your webhook endpoints," this component is the engine under that feature, not the feature. Budget separately for the admin surface, retry visibility, and dead-letter handling.

When to Consider This Package

Adopt when:

• The stack is PHP 8.1+ and Laravel/Symfony is already the platform, and you want webhook handling to look like the rest of your codebase rather than like a vendored SDK.
• You have 3 or more webhook directions (inbound providers, outbound customer endpoints, or internal service events) — the abstraction cost amortizes only past the first one or two.
• Signature verification and payload normalization are the actual risk surface (payments, entitlements, provisioning), and you want a reviewed implementation instead of hand-rolled HMAC comparison and JSON decoding per provider.
• You are already queue-driven — Messenger/queue integration means inbound verification stays thin and processing moves to workers, which is what you want for slow downstream side effects.
• You want to decouple from Serializer — since 7.2 the component no longer forces Symfony Serializer, so you can keep Laravel's own casting/validation conventions.
• You need to return multiple events from a single request (batch-style provider payloads) — supported since 7.2 via parsers returning multiple RemoteEvents.
• You want to pass the original request into parsing logic for tenant or routing decisions — supported since 7.2.

Look elsewhere when:

• The work is genuinely one endpoint. A controller plus hash_hmac with hash_equals is less code, fewer abstractions, and easier for a Laravel-only team to maintain. Adopting a framework component for a single receiver is resume-driven, not product-driven.
• You need a managed delivery surface — retries with backoff, replay, endpoint health, secret rotation, delivery logs. Buy (or build) that layer; this component deliberately does not provide it.
• Your provider's verification is unusual (asymmetric signatures, timestamp-tolerance windows with custom headers, XML/SOAP payloads, JWT-wrapped bodies). You will implement a parser regardless; evaluate whether the surrounding scaffolding is worth the dependency.
• You are pinned to PHP < 8.1, or locked to Laravel versions whose Symfony constraints conflict with the branch you need. Note v8 requires PHP ≥ 8.4 — most Laravel apps should pin the 7.x line deliberately, and that pin should be a written decision, not an accident of composer update.
• The team lacks Symfony literacy and has no appetite to acquire it. The "one line of validation" pitch oversells it: you still own request bridging, parser selection, secret management, event naming, and failure handling.
• You need vendor-neutral, language-agnostic webhook semantics across services (Node, Go, Python). Standardizing on a PHP-only component fragments the contract.

Gate before committing: run a spike on one real provider, measure the parser code volume honestly, and confirm the Symfony version constraint resolves against the actual Laravel/Symfony matrix in composer.lock. If the spike produces more glue than business logic, stop.

How to Pitch It (Stakeholders)

Executive summary. We have recurring webhook work on the roadmap — payment confirmations, status syncs, customer-configured event endpoints — and today each one is rebuilt from scratch, including the security-sensitive parts. This component is Symfony's maintained implementation of that plumbing: it verifies inbound signatures, normalizes payloads, and dispatches events, and it plugs into our existing queue infrastructure. The recommendation is a contained pilot on one high-value integration, not an org-wide standard, with a go/no-go on measured effort.

Why now, in business terms.

• Time-to-market: the commodity portion of an integration (verification, parsing, dispatch, retry-aware delivery) becomes configuration plus one parser class. On the order of a sprint saved per provider — a range we validate in the pilot, not a number we commit to today.
• Risk: signature verification and payload handling are where webhook incidents live — spoofed requests, replays, duplicate charges. Using a reviewed implementation with hash_equals-style verification and idempotency hooks is materially safer than per-provider hand-rolling, and it is auditable.
• Cost: no license cost (MIT), no vendor contract, no proprietary webhook service. The cost is engineering time plus one dependency we already carry transitively through the Symfony ecosystem.
• Reversibility: the abstraction is thin enough that a parser or transport can be replaced. This is a low-regret decision, which is why it does not need a large upfront business case.

For engineering. Treat it as scaffolding, not a framework. Inbound: bridge the request, select a parser, verify the signature, map to a RemoteEvent, dispatch onto the queue. Outbound: define transports and endpoints instead of scattering Http::post calls, so retry semantics live in one place. It is decoupled from Serializer as of 7.2, so your existing validation and casting stay intact. Concrete costs to plan for: pin the 7.x branch explicitly (v8 requires PHP 8.4), write the Laravel Request bridge helper once, and write the parser for our first provider — that parser is the pilot's real deliverable, and it is reusable regardless of whether we keep the component.

For security and compliance. Default posture improves: signature verification is a first-class concept rather than an afterthought, malformed payloads are rejected at the parser boundary, and idempotency keys protect financial and provisioning flows from duplicate processing. Two requirements come with adoption and must be owned: secret storage (config/Vault, with rotation) and network-level controls (IP allowlisting where the provider publishes ranges). Neither is provided by the package — say so plainly rather than implying the component covers them. Also note the component gives us hooks, not an audit log; we log webhook receipt ourselves.

Decision requested. Approve a two-week spike on a single integration, with success defined as: parser shipped and tested, version constraints resolved in composer.lock, and a written comparison of glue code written vs. glue code avoided. If the spike shows more bridging than business logic, we drop it and keep the parser.