Weave Code
Laravel Mailgun Webhooks Laravel Package
binary-cats/laravel-mailgun-webhooks
A Laravel package for receiving Mailgun webhooks: provides a webhook endpoint, verifies Mailgun signatures, and dispatches events for deliveries, opens, clicks, bounces, complaints, and unsubscribes so you can process email notifications cleanly.
Handle Mailgun webhooks in your Laravel application
Frequently asked questions about Laravel Mailgun Webhooks
- How do I install binary-cats/laravel-mailgun-webhooks?
- Install it with Composer as binary-cats/laravel-mailgun-webhooks, then publish the package config and register the webhook URL in your Mailgun dashboard. The package is a standard Laravel service provider integration, so no separate infrastructure is required for the endpoint itself. A queue backend such as Redis, SQS, or the database driver is still recommended so event handling does not run on the webhook request path.
- Does laravel-mailgun-webhooks verify Mailgun webhook signatures?
- Yes, the package verifies Mailgun signatures before dispatching events, which is the main reason to use it instead of a hand-rolled controller. The TPM assessment flags one detail to confirm during a spike: whether verification covers Mailgun's current HMAC signing scheme and how it handles the legacy versus current signing key distinction. Verification appears to be part of the endpoint's core behavior rather than an optional add-on, but check the config options in your installed version.
- Which Mailgun webhook events does this Laravel package dispatch?
- It dispatches events for deliveries, opens, clicks, bounces, complaints, and unsubscribes, per the package overview. Mailgun's full event taxonomy also includes temporary and permanent failures and stored events, so confirm in the source whether those are mapped to first-class events or handled generically. For anything outside the documented set, decide whether you need a generic fallback event or a small fork before relying on it in production.
- What Laravel and PHP versions does binary-cats/laravel-mailgun-webhooks support?
- The package targets Laravel applications on Composer-managed PHP 8.x runtimes, consistent with a modern Laravel monolith. The TPM assessment specifically calls out the Laravel and PHP support matrix as a question for the maintainer, because a small package can lag framework majors. Check the composer.json constraints and CI matrix in the repository before committing, and pin a version you have tested.
- How do I register the Mailgun webhook URL in Laravel?
- After installing and publishing config, the package exposes an HTTP endpoint that you point a Mailgun webhook at in the Mailgun dashboard. Because transport concerns like routing, signature verification, and payload parsing are handled by the package, your application code only subscribes to the typed events it cares about. If you already have a custom webhook controller, stand the package endpoint up on a parallel route first and compare normalized output before cutting over.
- Does laravel-mailgun-webhooks handle duplicate Mailgun webhooks or idempotency?
- Idempotency is not described as a built-in guarantee in the package overview, and the TPM assessment lists deduplication as an area most likely to be the consumer's responsibility. In practice you should dedupe on Mailgun's event or message IDs inside your listeners or a persistence layer before acting on an event. Mailgun retries webhooks, so treating handlers as at-least-once is the safe assumption unless you verify otherwise.
- Can Mailgun webhook events be processed on a queue in Laravel?
- The package dispatches Laravel events, so you can make your listeners implement ShouldQueue and move the actual work to a queue worker. Whether the package dispatches synchronously on the request path or supports queued dispatch out of the box is one of the open questions the TPM assessment recommends confirming. Either way, a Redis, SQS, or database queue is strongly recommended so Mailgun gets a fast 2xx response.
- What happens to unrecognized Mailgun event types in this package?
- The overview only names deliveries, opens, clicks, bounces, complaints, and unsubscribes, so behavior for unrecognized types is not documented there. The realistic possibilities are a silent drop, a generic event, or an exception, and the TPM assessment flags this as a question for the maintainer. Test with a sample payload for a type outside the documented list before you depend on Mailgun's full event taxonomy.
- Is binary-cats/laravel-mailgun-webhooks production-ready or should I use an alternative?
- It is architecturally a good fit for Laravel because it is a narrow ingress adapter that keeps Mailgun transport concerns out of domain code, and the most recent release is dated 2026-04-12, which suggests recent activity. The main risk is sustainability: roughly 64 stars and a single small vendor mean a low bus factor and limited community review. Treat it as a small, forkable dependency, keep your listeners behind your own event or interface, and have a plan to vendor the package if maintenance stalls.
- How do I test Mailgun webhooks locally in a Laravel app?
- You can point a Mailgun test webhook at the package endpoint, which is also the recommended way to compare normalized output against an existing custom controller during migration. For local development, send signed sample payloads through the route and assert that the expected events are dispatched, since signature verification will reject unsigned requests. Because the package's API surface is small and isolated, this kind of integration test is straightforward and also serves as your fork safety net.
Weaver
How can I help you explore Laravel packages today?