Mailgunwebhooks Bundle Laravel Package

Product Decisions This Supports

• Buy vs. build for email event persistence. Mailgun's free/low tier purges event logs after ~48 hours. This bundle persists webhook events in your own database with search, filter, detail views, and a pruning command. That is a real build-vs-buy decision: buying costs a dependency with 10 stars and 0 dependent projects; building costs roughly a sprint of webhook ingestion, schema, deduplication, and an admin UI. For a product where email is a secondary channel, the bundle wins on time-to-value; where email deliverability is the product, build and own it.
• Feature scoping for email observability. The bundle gives delivery/bounce/drop/open/click/spam-complaint capture plus an admin list view out of the box. That lets you defer a bespoke "email analytics" initiative (potentially a whole roadmap item) and instead ship a thin layer on top. The 5.0.0 release notes add replay/deduplication handling, which is the one thing that makes open/click metrics safe to report to stakeholders without manual de-duping — decide whether engagement reporting is in scope because dedupe now exists.
• Deliverability as a monitored SLI, not an incident. The bundle includes a CLI blacklist check against HetrixTools with admin email alerts, plus spam-complaint alerting. That converts "we found out we were on a blocklist from a customer" into a schedulable, alertable operational signal. 5.0.0 adds observable bounded retries on notifications, so failed alerts are visible rather than silently dropped — this is the difference between a runbook you can trust and one you can't.
• Security posture and compliance scope. 5.0.0 adds strict webhook signature validation and safe error responses. This is the item most likely to change a decision: an unauthenticated public ingestion endpoint that accepts forged events pollutes your event store and your metrics, and error responses that leak internals expand a security review you'd otherwise have to fund. Signature validation is a checkbox you can hand to a reviewer instead of a finding.
• Cost and infrastructure decisions. Pruning CLI (mailgun:delete-events) makes retention a dial rather than an unbounded storage liability, and HetrixTools' free tier (~3 checks/day) caps monitoring cost near zero. Both inform how you size the retention policy and whether paid observability tooling is warranted.
• Roadmap signal, not roadmap driver. The README's own TODO list (more tests, cleanup commands, more notification listeners, "write some CSS") plus the 5.0.0 jump to PHP 8.5 / Symfony 7.4 / Doctrine ORM 3 / Twig 3 / Symfony Mailer tells you this is a single-maintainer, burst-maintained project. Treat it as a component to wrap, not a platform to standardize on.

Critical caveat for this evaluation: this is a Symfony bundle, not a Laravel package. In a Laravel codebase it does not drop in — you would be either (a) running a Symfony bundle inside Laravel, which is not a supported path, or (b) mining the bundle for its webhook controller, entity schema, and blacklist-check logic and reimplementing them as Laravel listeners/commands. Option (b) is usually the honest answer, and it changes the build-vs-buy math substantially: you are buying a reference implementation, not a dependency.

When to Consider This Package

Consider it when:

• The stack is Symfony 7.x on PHP 8.5, or you are explicitly planning that upgrade. The 5.0.0 floors are aggressive; on Symfony 5/6 or PHP 8.1–8.3 you are pinned to an older major with weaker signature validation and no dedupe.
• Email is a meaningful but non-core channel — newsletters, transactional notifications, password resets — where you need history and bounce visibility but not a dedicated deliverability team.
• You are on a free or capped Mailgun tier and the 48-hour retention gap is a concrete, already-felt pain (e.g. "who received last week's newsletter?").
• You need blacklist monitoring and cannot justify a paid deliverability vendor.
• You want a reference architecture for signature validation, dedupe, and bounded-retry alerting that your team can port into Laravel rather than invent.

Look elsewhere when:

• The codebase is Laravel. There is no adapter, no service provider, no Laravel-native packaging. Zero dependent projects means no community-tested integration path exists — you are the first. Estimate the port cost before committing.
• You need vendor-backed support, an SLA, or a security disclosure process. Ten stars, one maintainer, no dependents.
• You need high-volume or multi-tenant event storage where dedupe, partitioning, and retention are first-class requirements — this stores events in your relational DB and expects MySQL/Doctrine.
• Your Mailgun plan already retains events long enough, or you have a paid ESP with a proper analytics API. Then you are paying a dependency for a gap you don't have.
• The team has no Symfony experience and no appetite to acquire it.
• You are pre-8.5 and unwilling to upgrade. Older majors lack the signature validation and dedupe that make the package defensible.

How to Pitch It (Stakeholders)

One-line framing: A small, MIT-licensed component that closes two gaps in our email pipeline — we lose delivery history after 48 hours, and we find out about deliverability problems late and by accident. Adopting it is a one-to-two sprint decision, not a platform bet, and the main constraint is that it's Symfony-shaped, so in our Laravel codebase we'd be adopting its design, not its code.

To executives: We currently cannot answer "did that campaign land?" a week later, and we learn about blocklisting from customers. This gives us retained delivery history, a searchable view, and automated blacklist/spam alerting. The 5.0.0 release adds webhook signature validation and duplicate-event handling — the two things that make the numbers trustworthy and the endpoint safe to expose. Cost is effectively zero in licensing and near-zero for the blacklist check on a free tier. Risk is maintenance: one maintainer, ten stars, no downstream users. Recommend adopting as an internal, wrapped capability with the schema and webhook logic under our own tests, so a stalled upstream doesn't stall us.

To engineering: Treat this as a reference implementation plus optional runtime dependency, not a framework commitment. The valuable, hard-to-get-right pieces are: strict webhook signature validation, idempotent event ingestion with dedupe, retry-with-backoff and observable failure on alert delivery, a retention/pruning command, and the blacklist-check job. On Symfony 7.4 / PHP 8.5 it's directly usable; on our Laravel stack we should port those five things — the bundle's entity schema and controller are a fine blueprint, and porting removes the single-maintainer and zero-dependents risk entirely. Either way, do not expose the webhook route without signature validation, and put the pruning command on a scheduler from day one so storage doesn't become the thing that forces a decision later.

Decision requested: Approve a timeboxed spike to (1) confirm our PHP/Symfony or Laravel target, (2) prototype signature-validated ingestion and dedupe in our stack, and (3) return a build-vs-port recommendation with effort estimate. Do not adopt as a pinned production dependency until that spike lands.