Laravel Flowguard Laravel Package

Product Decisions This Supports

• Build vs. buy for delivery reliability. FlowGuard bundles the three patterns most teams rebuild badly: a webhook inbox (dedupe inbound provider callbacks), a transactional outbox (avoid dual-write between DB commit and message/webhook emit), and reconciliation (detect and repair drift after the fact). That makes "build it ourselves" a much weaker default for any Laravel service touching third-party webhooks.
• Feature sequencing on integration-heavy roadmaps. Any roadmap item that depends on a provider callback — payments, refunds, subscription lifecycle, shipment/tracking updates, marketplace or ERP sync, KYC status — inherits duplicate-delivery and lost-message risk. Adopting this package is a prerequisite/enabler decision for those epics rather than a standalone feature bet.
• Incident-class prevention over incident response. Duplicate charges, double shipments, phantom order state, and "the webhook fired but the record never updated" are expensive, trust-damaging, and hard to reproduce. FlowGuard converts them from open-ended P1 classes into modeled, observable states with an inspection surface (flowguard:doctor).
• Scope and ownership boundary decisions. The package explicitly does not own tenant authentication, webhook signature verification, provider-side idempotency, timeouts/retries policy, approvals, downstream deduplication, or retention. Each of those is a decision your team must still make — useful for splitting work between platform and product squads and for rejecting "the library handles it" assumptions in planning.
• Buy-vs-adopt vs. hosted queue/streaming platforms. The outbox-plus-inbox model keeps reliability inside your own database and deployment, which is a different architectural commitment (and cost profile) than adopting SQS/Kafka/EventBridge or a managed webhook vendor. This is a roadmap-level architecture call, not just a library pick.
• Migration and upgrade budgeting. v1.0.2 is documentation and Composer discovery metadata only — no runtime, API, dependency, or schema change, and no data migration or fingerprint rewrite. Re-review cost is effectively zero, and existing operation/inbox/outbox/reconciliation identities must be preserved (populated rollback is rejected). That's a green light for pinning ^1.0 and planning upgrades as routine.
• Release-governance signal. The publish pipeline now evidences compatibility checks, clean-archive installation, demo-host and native-restore verification, immutable archive/checksum publication, Packagist indexing, and a fresh public install on the exact source. For a PM, that's a supply-chain hygiene argument to put in front of anyone who vets third-party dependencies.

When to Consider This Package

Adopt when:

• You run a Laravel application (the migrations and artisan commands imply Laravel conventions and a first-class DB) that receives webhooks from external providers and must act on them reliably.
• You have, or expect to have, dual-write risk: state committed to your DB plus a side effect (queue job, outbound call, provider notification) that can silently diverge. A transactional outbox is the standard mitigation.
• You need an auditable record of received and emitted messages for support, finance reconciliation, or dispute resolution.
• You want reconciliation as an operational routine — periodic sweeps comparing provider truth to local state — rather than ad-hoc scripts.
• Your team is small enough that a self-built reliability layer would be under-tested and under-observed, and you'd rather own configuration than internals.
• You can accept at-least-once delivery semantics and are prepared to make downstream consumers idempotent. This is not an exactly-once product; if the roadmap requires exactly-once guarantees, that's a design conversation, not a checkbox.
• You are willing to own the surrounding concerns yourself: tenant authentication, verified webhook acceptance, provider idempotency keys, timeouts and retry policy, approvals, downstream deduplication, and retention.

Look elsewhere or wait when:

• You are not on Laravel/PHP, or your persistence layer is not a relational DB you can run migrations against.
• Your throughput and ordering needs are event-streaming scale (partitioned logs, replay, consumer groups) — you want Kafka/Kinesis/Pulsar-type infrastructure, with the outbox at most as a bridge.
• You require a vendor-managed SLA, a hosted control plane, or an out-of-the-box webhook gateway with built-in signature verification and replay UI.
• Your organization gates third-party dependencies on completed independent human security/adopter review and representative production acceptance — both are stated as still open. Plan for a spike or a non-critical-service first deployment rather than a launch-critical dependency.
• You cannot accommodate the operational surface: new tables, an artisan flowguard:doctor health check to wire into monitoring, and reconciliation scheduling. Uninstrumented, these patterns create a false sense of safety.
• You need a documented deprecation/support-window policy or long-term vendor commitment before adopting — this is a single-maintainer package at v1.0.x; the release notes are strong on release engineering but do not establish a support contract.

How to Pitch It (Stakeholders)

To executives (one paragraph). We have a recurring, expensive failure mode: when an external provider tells us something happened — a payment cleared, an order shipped — our system sometimes processes it twice or misses it entirely, and we find out from a customer or a finance reconciliation weeks later. FlowGuard is a small, free, stable Laravel library that puts the standard industry remedy for this inside our own application: every inbound event is recorded once and processed once, every outbound side effect is committed atomically with our data, and a scheduled check compares our records against the provider's. It costs a Composer dependency and some engineering time, not a platform contract. It reduces duplicate-charge and double-shipment incidents, which are the incidents that cost us refunds, support hours, and trust. The trade-off is honest: the library provides the mechanics, and we still own authentication, signature verification, retry policy, and data retention — so this is a scoped engineering investment, not a hands-off purchase.

To engineering leadership. This is a Laravel package providing a webhook inbox, transactional outbox, reconciliation, and fault-tolerance primitives, installable via composer require mykholy/laravel-flowguard:^1.0 with migrations and a flowguard:doctor health command. The value is that it replaces homegrown, under-tested glue with a versioned contract and named integration boundaries. v1.0.2 is documentation and Composer metadata only — runtime code, API signatures, dependencies, and schema are unchanged, so there is no migration, no fingerprint rewrite, and effectively zero upgrade risk; existing operation, inbox, outbox, and reconciliation identities must be preserved, and populated rollback is rejected. Pin ^1.0. Be explicit with the team about the boundaries: delivery is at-least-once, so consumers must be idempotent; the host owns tenant auth, verified webhook acceptance, provider idempotency, timeouts, approvals, downstream dedupe, and retention. Independent security/adopter review and representative production acceptance are still open, so I'd sequence this behind a spike or into a non-critical-path service first, and wire the doctor command into our existing alerting from day one.

To security and platform reviewers. The release process itself is a positive signal: compatibility, clean-archive installation, demo-host and native-restore verification on the exact release source, immutable archive/checksum publication, Packagist indexing, and a fresh public installation from the published artifact. The package is explicit that it does not assert verified webhook acceptance or tenant isolation — those remain our responsibility and should be reviewed as part of our own integration design, not attributed to the dependency. Recommend: pin the version, record the checksum, and treat the open independent review as a tracked risk item with a named owner.