Postmark Webhooks Laravel Laravel Package

Product Decisions This Supports

• Build vs. buy for email event ingestion. Postmark webhooks (delivery, bounce, spam complaint, open, click, inbound) are a well-defined, low-variance surface. This package converts them into a single PostmarkWebhookReceived event with payload, email, recordType, and messageId already extracted — roughly a day of engineering you don't have to spend, at the cost of a very small dependency.
• Feature scoping for lifecycle messaging. Enables roadmap items such as suppression-list management, bounce/complaint-driven list hygiene, delivery-failure alerting for account managers, and inbound-email-to-ticket pipelines — all as listeners rather than as new infrastructure.
• Keep the domain layer ours. Because there are no migrations or models, the package makes no claim on our schema. The PM decision shifts from "which email-events data model do we adopt?" to "which listeners do we own?" That is a materially cheaper and more reversible commitment.
• Delivery-risk tradeoff on upgrade cadence. v2.3.0 changed firewall behavior in a minor release: non-production environments no longer bypass an enabled firewall. That's a deliberate decision to trade an implicit dev convenience for consistent auth. It sets a planning constraint — review minor bumps on ^2.0 before lock-file updates — which is worth budgeting as recurring maintenance cost.
• Security posture as a product requirement. Source-IP allowlisting against Postmark's four published IPs plus optional Basic Auth is included. If compliance or a security review has flagged unauthenticated inbound webhooks, this satisfies it without a bespoke middleware project.
• Not a fit for: multi-provider email strategy. If the roadmap anticipates SendGrid/SES/Resend alongside Postmark, a Postmark-specific adapter bakes in a decision better made at the abstraction layer.

When to Consider This Package

Adopt when all of the following hold:

• The application is Laravel 12 or 13 on PHP 8.3–8.5 and will stay current. The package tracks the two most recent majors; a stalled Laravel upgrade path becomes a blocker.
• The team already uses Laravel's event system for async work. If events aren't an established pattern, you're introducing a paradigm to save boilerplate — a bad trade.
• Email event handling is genuinely needed now, not speculative. Zero stars and zero dependents mean you are substantively the first production user; that's acceptable for a ~200-line adapter with tests, PHPStan level 9, and Pint, but not for anything load-bearing in a regulated flow without a read-through of the source.
• You accept owning listeners, queueing, retries, idempotency (dedupe on messageId), and rate limiting yourself. The package explicitly provides none of this — it returns ["success"] and steps aside. Postmark will retry; your handlers must tolerate duplicates.
• Firewall configuration is an explicit, reviewed decision per environment. Plan a matrix: production and staging keep it enabled and verify trusted-proxy/Basic Auth; local and CI set POSTMARK_WEBHOOK_FIREWALL_ENABLED=false or configure the switch in the test application. Rebuild config caches after changes.

Look elsewhere when: you need persistence or replay of webhook history out of the box (the package it was inspired by, mvdnbrk/laravel-postmark-webhooks, adds models and migrations); you need a provider-agnostic webhook abstraction; you want a maintained dependency with community support and a track record; or your security review requires a vendored, audited codebase rather than a Composer dependency.

How to Pitch It (Stakeholders)

For executives. We can turn Postmark's email events — bounces, complaints, opens, clicks, inbound mail — into product behavior in days rather than weeks. This package is a thin, MIT-licensed adapter that receives Postmark's callbacks, verifies they genuinely came from Postmark, and hands us a clean event to act on. It carries no database schema, no vendor lock-in on our data model, and no new infrastructure. Cost is one small dependency and roughly an afternoon of integration; the alternative is our own build of the same webhook endpoint, auth, and parsing. The main risks are maturity (it has effectively no external users yet) and a recent minor-version behavior change to firewall enforcement that we must configure deliberately per environment.

For engineering. A single route (/api/postmark/webhook, configurable), a PostmarkWebhookReceived event exposing payload, email, recordType, and messageId, and middleware doing IP allowlisting plus optional Basic Auth. No migrations, no models — you write listeners and own everything downstream: queueing, idempotency on messageId, retry semantics, error logging, and throttling.

Two things to flag before we commit:

1. v2.3.0 is an intentional behavior change in a minor release. APP_ENV no longer bypasses an enabled firewall. Anything on ^2.0 can pick this up during a routine dependency update. We should pin or review minor bumps and confirm our trusted-proxy and Basic Auth setup holds — especially behind a load balancer.
2. Adoption risk is real. Zero stars, zero dependents, no external bug reports means no proven edge-case surface for malformed payloads or proxy configurations. Mitigation is cheap and worth doing: read the source before merging, and wrap webhook handling behind our own event so swapping adapters later is a one-file change.

Ask: approve a timeboxed spike — integrate against a Postmark test server, exercise one bounce and one delivery listener end-to-end, and confirm the environment firewall matrix in CI before we adopt.