- How do I install citricguy/postmark-webhooks-laravel?
- Install it with Composer by running composer require citricguy/postmark-webhooks-laravel. Laravel package auto-discovery registers the service provider, so no manual provider entry is needed. You can publish the configuration file if you want to change the route, middleware, or firewall settings, then point your Postmark server webhook at the default endpoint. The package requires Laravel 12.x or 13.x, PHP 8.3, 8.4, or 8.5, and an active Postmark account.
- Which Laravel and PHP versions does this Postmark webhook package support?
- The package targets Laravel 12.x and 13.x running on PHP 8.3, 8.4, or 8.5. If your application is on an older Laravel or PHP release, you should check the tagged releases for a compatible version before installing. Keeping the package on a version that matches your framework support matrix avoids install conflicts in Composer.
- How do I configure the webhook URL in my Postmark account?
- In your Postmark server, open settings, then webhooks, then add webhook, and enter your endpoint URL. The default route is https://your-domain.com/api/postmark/webhook, and it is configurable in config/postmark-webhooks.php if you need a different path. Select the Postmark events you want delivered and save; every delivery will then be turned into a Laravel event in your app.
- How do I listen for the PostmarkWebhookReceived event?
- Register a listener for Citricguy\PostmarkWebhooks\Events\PostmarkWebhookReceived in your EventServiceProvider's $listen array, then handle the logic in the listener class. The raw Postmark payload is available as $event->payload, and the email address, record type, and message ID are exposed as additional properties on the event. Because the package dispatches only this single event, you keep all business logic in your listeners and out of the webhook endpoint itself. Use php artisan make:listener to scaffold the listener.
- Does this package add migrations or database models?
- No. There are no migrations, no models, and no persistence layer, so installing the package will not touch your database. It only accepts the Postmark request, verifies it, and fires an event. If you want to store webhook data, you do that yourself inside a listener.
- How does the package verify that webhook requests actually come from Postmark?
- The package ships middleware that acts as a firewall, checking requests against Postmark's source IPs and, when configured, HTTP Basic Auth credentials. It is enabled by default and controlled by the POSTMARK_WEBHOOK_FIREWALL_ENABLED environment variable. If you run behind a load balancer or reverse proxy, make sure your trusted proxy configuration is correct so the real client IP is used for the check. Successful deliveries get an HTTP 200 response with a success JSON body, and an HTTP 202 compatibility setting is available if you need it.
- How do I disable the Postmark webhook firewall for local development or tests?
- Set POSTMARK_WEBHOOK_FIREWALL_ENABLED=false in your local .env file or in the environment configuration of your isolated test application. After changing any environment value, run php artisan config:clear or rebuild the config cache, otherwise a stale cache can keep the old firewall behavior. Never leave the firewall disabled in a shared or publicly reachable environment, since that removes the authentication check on the endpoint.
- Why did my local or staging webhook requests start failing after upgrading to v2.3.0?
- In v2.3.0 the firewall is now controlled consistently by POSTMARK_WEBHOOK_FIREWALL_ENABLED in every environment, so APP_ENV=local, testing, or staging no longer bypasses an enabled firewall. Any synthetic request or proxy setup that previously relied on the non-production escape hatch will now be rejected. Explicitly set the firewall variable to false where you accept test traffic, or verify your source IP, proxy, and Basic Auth configuration on staging. Because this is a behavior change in a minor release, review lock-file updates that pull v2.3.0 into an existing ^2.0 constraint.
- How do I test Postmark webhook handling in my Laravel test suite?
- Disable the firewall in your test environment, post a synthetic Postmark-shaped payload to the route, and use Event::fake to assert that PostmarkWebhookReceived was dispatched with the expected email, record type, and message ID. Keep listener assertions in separate tests so a change in parsing does not break your webhook endpoint test. If you use an isolated test application, set the same firewall switch there rather than relying on APP_ENV. Remember to clear or rebuild cached configuration after changing the variable.
- Is this package worth using, or should I write my own Postmark webhook controller?
- It is a deliberately thin package: one route, one middleware-backed firewall, and one event, with no database footprint, which makes it cheap to adopt and easy to replace later. The trade-off is limited community adoption and a Postmark-specific payload shape, so edge cases such as malformed payloads, rate limiting, and unusual proxy setups are not heavily documented. If you need custom parsing, multi-provider support, or queue-level control, writing your own controller is a reasonable alternative, since the package only saves you the parsing and verification boilerplate. Track its release notes before upgrading, because behavior changes like the v2.3.0 firewall handling can land in a minor version.