Receiver Laravel Package

Product Decisions This Supports

• Build vs. buy for webhook ingestion. Inbound webhook handling is undifferentiated heavy lifting — signature verification, timestamp windows, event-name-to-class mapping, queue dispatch. This package turns that into a config table. Adopting it removes a recurring "we need to spend a sprint integrating vendor X's webhooks" line item from the roadmap and converts it into a config-plus-handler task.
• Provider coverage as a roadmap unlock. The five new providers (Shopify, Twilio, Mailchimp, SendGrid, Paddle Billing) hit four of the most common integration asks in commerce, messaging, marketing, and billing. That directly de-risks roadmap items gated on "we can't take payments/messaging events reliably yet." Paddle's HMAC-SHA256 with key rotation matters specifically for billing: it makes secret rotation a supported operational procedure rather than a bespoke hack, which is a compliance-adjacent requirement in payments work.
• Batched-event payloads are now addressable. Multiple events per request (getEvent() returning an array of event_name => eventData pairs, with a separate handler dispatched per event) unlocks providers that batch — SendGrid named explicitly. This is the difference between "we can't support this vendor without a shim" and "we can." It also means one delivery failure no longer risks silently dropping sibling events in the same payload, provided handlers are idempotent — a design constraint worth stating in the tech spec.
• Community provider ecosystem changes the sourcing model. php artisan receiver:make MyProvider --provider scaffolds a provider class and a companion ServiceProvider for package auto-discovery. That makes third-party providers publishable as standalone Composer packages. Product implication: long-tail vendor integrations become a community/partner contribution channel instead of an internal backlog item. Worth a deliberate decision — do we accept community providers as dependencies, and what's the review bar?
• Security review surface is now answerable. Enhanced Postmark verification with three combinable strategies (auth HTTP Basic Auth, headers custom headers, ips against Postmark's published webhook IPs) means we can meet enterprise security questionnaires with configuration rather than custom code. Combinable strategies are the right shape: security teams rarely accept one control.
• Silent-failure bugs closed. Two fixes remove failure modes that would have surfaced as "the integration just doesn't fire" support tickets: GitHub event names no longer carry a trailing _ when there's no action field (push, fork), and event names are fully lowercased before class resolution so ALL_CAPS names like PayPal's PAYMENT.AUTHORIZATION.CREATED resolve correctly. These are the highest-cost class of bug we can inherit — silent, intermittent, hard to attribute.
• Platform-lifecycle risk is now measurable. CI covers Laravel 10/11/12/13 across PHP 8.2/8.3/8.4, with PHPStan level 5 and Pint. That gives us a defensible answer to "will this survive our framework upgrade?" during architecture review — a concrete input to any upgrade-train planning.

When to Consider This Package

Adopt when:

• You're on Laravel and need inbound webhooks from one or more of the supported providers (Shopify, Twilio, Mailchimp, SendGrid, Paddle, Postmark, GitHub, PayPal, and the rest of the built-in set).
• You want vendor signature verification done correctly by default rather than reimplemented per integration — particularly HMAC-SHA256, HMAC-SHA1, ECDSA SHA-256 (SendGrid, opt-in), and URL-secret-param schemes.
• You have a long tail of providers and want a paved road: the scaffolding command plus auto-discovered ServiceProvider means the marginal cost of the next integration is low, whether written internally or pulled from the community.
• You need combinational verification (IP allowlist + header + basic auth) to satisfy a security review without custom middleware.
• You're planning an upgrade train across Laravel 10–13 / PHP 8.2–8.4 and want a dependency with a matching CI matrix.

Look elsewhere or plan to wrap it when:

• You need durable, replayable event infrastructure — at-least-once delivery guarantees, dead-letter queues, event replay, or a persistent audit trail. This is a receiving/verification/dispatch layer, not an event bus; pair it with your queue and a persistence layer.
• You need payload schema validation, versioning, or contract testing per provider — not in scope here.
• You're not on Laravel — the value is concentrated in the framework integration (service provider, config, artisan, dispatch), so porting leaves mostly the signature logic.
• You need outbound webhooks to your own customers; this is inbound-only.
• You require vendor providers outside the built-in set and are unwilling to own (or vet) a community package — check the ecosystem's maturity before assuming coverage.
• You're multi-tenant with per-tenant signing secrets at scale: key rotation is present for Paddle, but per-tenant secret resolution patterns should be validated against your tenancy model before commit.
• SendGrid ECDSA is opt-in — confirm the team enables it rather than defaulting to a weaker path, and write that into the integration checklist.

How to Pitch It (Stakeholders)

For executives: Webhook ingestion is plumbing that every integration needs and no customer ever sees, and we have been paying for it repeatedly — once per vendor, in engineering time and in production incidents. This release turns that into configuration. Five new providers land in one version (Shopify, Twilio, Mailchimp, SendGrid, Paddle Billing), which covers most of the commerce, messaging, marketing, and billing integrations on our roadmap. More strategically, the new scaffolding command lets partners and the community publish their own providers as installable packages — meaning long-tail vendor support can scale without scaling our headcount. There are no breaking changes and no upgrade cost; adoption is additive.

For engineering: Add provider entries to config/services.php per the rewritten README; no breaking changes. Three things to note in the tech spec: (1) getEvent() may now return an array of event_name => eventData pairs with a separate handler dispatched per event — every handler must be idempotent, since batched deliveries make partial-failure more likely and retries more consequential; (2) Postmark verification now supports auth, headers, and ips strategies in combination — use combinations where the vendor publishes IPs, and turn on SendGrid's ECDSA SHA-256 rather than leaving it opt-in-off; (3) provider classes and their auto-discovered ServiceProvider can now be shipped as standalone Composer packages, so we need a review bar for any community provider we accept as a dependency (pinned version, CI green, signature logic readable). Two naming fixes worth knowing about: GitHub events without an action field no longer get a trailing _ (push, fork now map correctly), and event names are fully lowercased before class resolution so ALL_CAPS names such as PayPal's PAYMENT.AUTHORIZATION.CREATED resolve to the expected handler. Tooling to adopt in our own pipeline: PHPStan level 5, Pint, and the composer run lint / lint:check / analyse scripts. CI now spans Laravel 10–13 on PHP 8.2–8.4, which is our upgrade-train answer.