Add webhook push support

Author: damms005

README.md

@@ -276,6 +276,71 @@ The Terminal class throws `\Exception` on failures. Common scenarios include:
 
 Always wrap Terminal method calls in try-catch blocks for proper error handling.
 
+## Webhook Push Notifications
+
+When a payment succeeds, this package can automatically send a webhook to an external system (e.g. a financial tracking service). This uses [spatie/laravel-webhook-server](https://github.com/spatie/laravel-webhook-server) under the hood.
+
+### Setup
+
+1. Install the webhook server package:
+
+```bash
+composer require spatie/laravel-webhook-server
+```
+
+2. Set the webhook URL and signing secret in your `.env`:
+
+```env
+LARAVEL_MULTIPAY_WEBHOOK_URL=https://your-receiving-app.com/api/webhooks/payments
+LARAVEL_MULTIPAY_WEBHOOK_SIGNING_SECRET=your-shared-secret
+```
+
+3. Create a class that implements `Damms005\LaravelMultipay\Contracts\WebhookPayloadPackager`:
+
+```php
+use Damms005\LaravelMultipay\Models\Payment;
+use Damms005\LaravelMultipay\Contracts\WebhookPayloadPackager;
+
+class MyWebhookPayloadPackager implements WebhookPayloadPackager
+{
+    public function getWebhookPayload(Payment $payment): array
+    {
+        return [
+            'transaction_reference' => $payment->transaction_reference,
+            'amount_paid' => $payment->original_amount_displayed_to_user,
+            'payment_processor_name' => $payment->payment_processor_name,
+            // ...add any app-specific data you need
+        ];
+    }
+}
+```
+
+4. Register your packager in a service provider:
+
+```php
+config()->set(
+    'laravel-multipay.webhook.payload_packager',
+    \App\Services\MyWebhookPayloadPackager::class,
+);
+```
+
+Once configured, every `SuccessfulLaravelMultipayPaymentEvent` will trigger a signed webhook POST to the configured URL with the payload returned by your packager.
+
+### Backfilling Existing Payments
+
+To send existing successful payments to the webhook endpoint:
+
+```bash
+php artisan multipay:send-payments-webhook
+```
+
+Options:
+- `--from=YYYY-MM-DD` — only payments created on or after this date
+- `--to=YYYY-MM-DD` — only payments created on or before this date
+- `--chunk=100` — number of payments per batch (default: 100)
+
+The command fail-fast aborts after 3 consecutive batch failures.
+
 ## Testing
 
 ```bash

database/migrations/2026_02_12_120000_add_webhook_dispatched_at_to_payments_table.php

@@ -0,0 +1,26 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function up(): void
+    {
+        $prefix = config('laravel-multipay.table_prefix', '');
+
+        Schema::table("{$prefix}payments", function (Blueprint $table) {
+            $table->timestamp('webhook_dispatched_at')->nullable()->after('deleted_at');
+        });
+    }
+
+    public function down(): void
+    {
+        $prefix = config('laravel-multipay.table_prefix', '');
+
+        Schema::table("{$prefix}payments", function (Blueprint $table) {
+            $table->dropColumn('webhook_dispatched_at');
+        });
+    }
+};

src/Commands/SendExistingPaymentsToWebhook.php

@@ -43,7 +43,7 @@ public function handle(): int
             return self::FAILURE;
         }
 
-        $query = Payment::successful();
+        $query = Payment::successful()->whereNull('webhook_dispatched_at');
 
         if ($from = $this->option('from')) {
             $query->where('created_at', '>=', $from);
@@ -76,6 +76,7 @@ public function handle(): int
                     ->useSecret($signingSecret)
                     ->dispatch();
 
+                Payment::whereIn('id', $payments->pluck('id'))->update(['webhook_dispatched_at' => now()]);
                 $this->sentCount += $payments->count();
                 $this->consecutiveFailures = 0;
             } catch (\Exception $e) {

src/Listeners/SendPaymentWebhookListener.php

@@ -29,6 +29,8 @@ public function handle(SuccessfulLaravelMultipayPaymentEvent $event): void
             ->payload($payload)
             ->useSecret(config('laravel-multipay.webhook.signing_secret'))
             ->dispatch();
+
+        $event->payment->update(['webhook_dispatched_at' => now()]);
     }
 
     public static function buildPayload(Payment $payment): ?array