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 the path key in the config/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 example SpamComplaint will be saved as spam_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.

mvdnbrk / laravel-postmark-webhooks

Maintainers

Details