mvdnbrk / laravel-postmark-webhooks
Handle Postmark webhooks in a Laravel application.
Fund package maintenance!
mvdnbrk
Installs: 34 973
Dependents: 0
Suggesters: 0
Security: 0
Stars: 25
Watchers: 4
Forks: 11
Open Issues: 5
Requires
- php: ^7.2 || ^8.0
- illuminate/support: ^6.0 || ^7.0 || ^8.0 || ^9.0
Requires (Dev)
- orchestra/testbench: ^4.5 || ^5.0 || ^6.0 || ^7.0
- phpunit/phpunit: ^8.5 || ^9.3
README
Handle Postmark webhooks in a Laravel application
Postmark can send out several webhooks to your application when an event occurs.
This way Postmark is able to immediately notify you when something new occurs.
This package can help you handle those webhooks.
Installation
You can install the package via composer:
composer require mvdnbrk/laravel-postmark-webhooks
This package will log all incoming webhooks to the database by default.
Run the migrations to create a postmark_webhook_logs
table in the database:
php artisan migrate
If you want to disable database logging you can set
POSTMARK_WEBHOOKS_LOG_ENABLED=false
in your.env
file.
Setup webhooks with Postmark
Visit the servers page on your Postmark account.
Choose the server you want to setup webhooks for.
Go to settings
> webhooks
> add webbook
.
This package will register a route where Postmark can post their webhooks to: /api/webhooks/postmark
.
Fill in your webhook URL: https://<your-domain.com>/api/webhooks/postmark
Pick the events Postmark should send to you and save the webhook.
You are ready to receive webhook notifications from Postmark!
You may change the
/api/webhooks/postmark
endpoint to anything you like.
You can do this by changing thepath
key in theconfig/postmark-webooks.php
file.
Protection of your webhook
This package protects your webhook automatically by only allowing requests from the IP range that Postmark uses.
Usage
Postmark can send out several event types by posting a webhook.
You can find the full list of webhooks in the Postmark documentation.
All webhook requests will be logged in the postmark_webhook_logs
table.
The table has a payload
column where the entire payload of the incoming webhook is saved.
The ID Postmark assigned to the original message will be saved in the message_id
column,
the event type will be stored in the record_type
column and the email address as well in the email
column.
Note that event types will be converted to
snake_case
.
For exampleSpamComplaint
will be saved asspam_complaint
.
Events
Whenever a webhook call comes in, this package will fire a PostmarkWebhookCalled
event.
You may register an event listener in the EventServiceProvider
:
/** * The event listener mappings for the application. * * @var array */ protected $listen = [ PostmarkWebhookCalled::class => [ YourListener::class, ], ];
Example of a listener:
<?php namespace App\Listeners; use Mvdnbrk\PostmarkWebhooks\Events\PostmarkWebhookCalled; class YourListener { /** * Handle the event. * * @param \Mvdnbrk\PostmarkWebhooks\Events\PostmarkWebhookCalled $event * @return void */ public function handle(PostmarkWebhookCalled $event) { // Do your work here. // You can access the payload here with: $event->payload. // The email address, message ID and record type are also available: // $event->email // $event->messageId // $event->recordType } }
You may also register an event listener for a specific type of event:
/** * The event listener mappings for the application. * * @var array */ protected $listen = [ 'webhook.postmark: spam_complaint' => [ YourSpamComplaintListener::class, ], ];
Available events: open
, bounce
, click
, delivery
, spam_complaint
.
Advanced configuration
You may optionally publish the config file with:
php artisan vendor:publish --provider="Mvdnbrk\PostmarkWebhooks\PostmarkWebhooksServiceProvider" --tag="config"
Within the configuration file you may change the table name being used or the Eloquent model being used to save log records to the database.
If you want to use your own model to save the logs to the database you should extend the
Mvdnbrk\PostmarkWebhooks\PostmarkWebhook
class.
You can also exclude one or more event types from being logged to the database.
Place the events you want to exclude under the except
key:
'log' => [ ... 'except' => [ 'open', ... ], ],
You can map the events fired by this package to your own event classes:
'events' => [ 'spam_complaint' => App\Events\SpamComplaint, ... ],
Change log
Please see CHANGELOG for more information on what has changed recently.
Testing
$ composer test
Contributing
Please see CONTRIBUTING for details.
Security Vulnerabilities
Please review our security policy on how to report security vulnerabilities.
Credits
Inspired by Laravel Stripe Webooks from Spatie.
License
The MIT License (MIT). Please see License File for more information.