Postmark Webhooks Laravel Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require citricguy/postmark-webhooks-laravel
   

   Publish the config file:

   php artisan vendor:publish --provider="Citricguy\PostmarkWebhooks\PostmarkWebhooksServiceProvider"
   

2. Configure Webhook Secret Edit config/postmark-webhooks.php and set:

   'secret' => env('POSTMARK_WEBHOOK_SECRET'),
   

   Add to .env:

   POSTMARK_WEBHOOK_SECRET=your_postmark_webhook_signature_secret
   

3. Define a Webhook Route Add to routes/web.php:

   Route::post('/postmark-webhook', [\Citricguy\PostmarkWebhooks\PostmarkWebhooksController::class, 'handle']);
   

4. First Use Case: Handling Delivered Emails Create a listener for the delivered event:

   php artisan make:listener HandleDeliveredEmail
   

   Update app/Listeners/HandleDeliveredEmail.php:

   public function handle(Delivered $event) {
       Log::info('Email delivered:', ['message_id' => $event->messageId]);
   }
   

   Register the listener in EventServiceProvider.

Implementation Patterns

Core Workflow

1. Event-Based Processing

   • Postmark webhooks trigger Laravel events (e.g., Delivered, Opened, Bounced).
   • Map Postmark events to Laravel listeners for business logic.

2. Validation & Security

   • The package automatically validates the X-Postmark-Signature header.
   • Use middleware to enforce HTTPS for webhook routes:

     Route::post('/postmark-webhook', [PostmarkWebhooksController::class, 'handle'])
          ->middleware('web', 'signed', 'throttle:60');
     

3. Dynamic Event Handling

   • Extend Citricguy\PostmarkWebhooks\Events\PostmarkEvent for custom events:

     class CustomEvent extends PostmarkEvent {
         public function __construct(array $data) {
             parent::__construct($data, 'custom_event');
         }
     }
     

   • Register in PostmarkWebhooksServiceProvider:

     $this->events['custom_event'] = \App\Events\CustomEvent::class;
     

4. Queueing Heavy Tasks

   • Dispatch long-running tasks to queues:

     public function handle(Delivered $event) {
         HandleEmailDelivery::dispatch($event->messageId);
     }
     

Integration Tips

• Postmark Dashboard Setup Configure webhook URL in Postmark:

  https://your-app.com/postmark-webhook
  

  Select events (e.g., Delivered, Opened) and use the generated secret.

• Testing Webhooks Use Postmark’s test mode or tools like webhook.site to simulate events.

• Logging & Monitoring Log raw payloads for debugging:

  Log::debug('Postmark webhook payload:', $event->payload);
  

Gotchas and Tips

Pitfalls

1. Secret Mismatch

   • If the X-Postmark-Signature header fails validation, the request is rejected silently.
   • Fix: Verify the secret matches Postmark’s generated signature in the dashboard.

2. Missing Events

   • Only events explicitly configured in Postmark’s dashboard will trigger.
   • Fix: Ensure all required events are enabled in Postmark.

3. Rate Limiting

   • Postmark may throttle rapid webhook deliveries.
   • Fix: Use Laravel’s throttle middleware or queue listeners.

4. Payload Parsing

   • The package expects raw JSON payloads. Malformed payloads may cause errors.
   • Fix: Add error handling in listeners:

     try {
         // Process event
     } catch (\Exception $e) {
         Log::error('Webhook processing failed:', ['error' => $e->getMessage()]);
     }
     

Debugging Tips

• Enable Debug Logging Add to config/postmark-webhooks.php:

  'debug' => env('APP_DEBUG', false),
  

  Logs raw payloads and validation steps.

• Verify Headers Check the X-Postmark-Signature and X-Postmark-Id headers in incoming requests:

  dd(request()->header());
  

Extension Points

1. Custom Event Mapping Override the default event mapping in PostmarkWebhooksServiceProvider:

   protected function mapEvents(): array {
       return [
           'delivered' => Delivered::class,
           // Override or add custom mappings
       ];
   }
   

2. Middleware for Preprocessing Add middleware to modify payloads before event dispatch:

   Route::post('/postmark-webhook', [PostmarkWebhooksController::class, 'handle'])
        ->middleware(\App\Http\Middleware\SanitizeWebhookPayload::class);
   

3. Webhook Retries Implement retry logic for failed events using Laravel’s retry helper or a queue job:

   public function handle(Failed $event) {
       Retry::until(
           fn() => $this->processFailedEmail($event),
           maxAttempts: 3
       );
   }