Filament Webhook Client Laravel Package

Getting Started

Minimal Setup

1. Prerequisites: Ensure spatie/laravel-webhook-client is installed and configured in your Laravel project.
2. Installation:

   composer require tapp/filament-webhook-client:"^4.0"
   

3. Publish Config:

   php artisan vendor:publish --tag="filament-webhook-client-config"
   

4. Register Plugin: Add to app/Providers/Filament/PluginServiceProvider.php:

   public function register(): void
   {
       Filament::registerPlugin(
           Tapp\FilamentWebhookClient\FilamentWebhookClientPlugin::make()
       );
   }
   

First Use Case

• View Webhooks: Access the Filament admin panel (e.g., /admin/resources/webhooks) to see all registered webhooks.
• Create/Edit: Use the built-in CRUD interface to manage webhooks (e.g., add a new Stripe webhook or update a PayPal one).
• Test Webhooks: Trigger a test webhook via the UI to verify functionality without external calls.

Implementation Patterns

Core Workflows

1. Resource Integration:

   • The package provides a pre-built Filament resource for Spatie\WebhookClient\Models\Webhook.
   • Extend or override the resource by publishing and modifying:

     php artisan vendor:publish --tag="filament-webhook-client-resources"
     

   • Customize fields, tables, or forms in app/Filament/Resources/WebhookResource.php.

2. Policy Management:

   • The package includes a default policy for webhook management (e.g., ViewWebhooks, ManageWebhooks).
   • Assign policies to users/groups in app/Providers/Filament/AdminPanelProvider.php:

     $panel->userMenuItems([
         Filament\Panel\UserMenuItem::make('Webhooks')
             ->url(fn (Filament\User $user) => $user->can('view webhooks') ? '/admin/resources/webhooks' : null),
     ]);
     

3. Webhook Events:

   • Listen to webhook events (e.g., WebhookReceived) in EventServiceProvider:

     protected $listen = [
         \Spatie\WebhookClient\Events\WebhookReceived::class => [
             \App\Listeners\HandleWebhook::class,
         ],
     ];
     

   • Log or process events in the listener, then reflect changes in Filament via real-time updates (e.g., using Filament’s notifications).

4. Testing Webhooks:

   • Use the Filament UI to send test payloads to a local endpoint (e.g., POST /webhook/test).
   • Mock external services (e.g., Stripe) in tests:

     $webhook = Webhook::find(1);
     $webhook->test();
     

Advanced Patterns

• Dynamic Configuration: Bind webhook configurations to Filament settings. For example, store API keys in Filament’s settings panel and inject them into webhook handlers:

  // In a webhook handler
  $apiKey = Filament::getSettings()['stripe_api_key'];
  

• Webhook Groups: Organize webhooks by service (e.g., "Stripe," "PayPal") using Filament’s resource grouping:

  public static function getRelations(): array
  {
      return [
          Tables\Relationships\BelongsToMany::make('Services')
              ->relationship('services', Service::class)
              ->title('Service'),
      ];
  }
  

• Real-Time Updates: Use Filament’s livewire components to update the UI when a webhook is received:

  use Filament\Notifications\Notification;
  
  // In a listener
  Notification::make()
      ->title('Webhook Received')
      ->success()
      ->send();
  

Gotchas and Tips

Pitfalls

1. Missing Spatie Webhook Client:

   • Error: Class 'Spatie\WebhookClient\Models\Webhook' not found.
   • Fix: Ensure spatie/laravel-webhook-client is installed and configured before installing this package.

2. Policy Conflicts:

   • Error: Call to undefined method Filament\Resources\Resource::can().
   • Fix: Verify policies are correctly assigned in Filament/AdminPanelProvider.php and that the FilamentWebhookClientPlugin is registered.

3. Webhook Secret Mismatch:

   • Error: Webhook verification fails with Invalid signature.
   • Fix: Ensure the webhook_secret in .env matches the one configured in the Filament UI or code.

4. Resource Overrides Not Loading:

   • Error: Custom fields/tables in WebhookResource are ignored.
   • Fix: Clear Filament’s cache:

     php artisan filament:cache-reset
     

Debugging Tips

• Log Webhook Payloads: Add a middleware to log incoming webhook payloads for debugging:

  // app/Http/Middleware/LogWebhookPayload.php
  public function handle($request, Closure $next)
  {
      if ($request->is('webhook/*')) {
          \Log::info('Webhook Payload', $request->all());
      }
      return $next($request);
  }
  

• Test Locally: Use tools like ngrok to expose a local endpoint for testing webhooks:

  ngrok http 8000
  

  Configure the webhook URL in Filament to point to your ngrok endpoint (e.g., https://abc123.ngrok.io/webhook/stripe).

Extension Points

1. Custom Webhook Models: Extend the default Webhook model to add custom fields:

   // app/Models/CustomWebhook.php
   class CustomWebhook extends \Spatie\WebhookClient\Models\Webhook
   {
       protected $casts = [
           'custom_field' => 'boolean',
       ];
   }
   

   Update the Filament resource to use the custom model.

2. Add Custom Actions: Extend the WebhookResource to include custom actions (e.g., "Regenerate Secret"):

   public static function getActions(): array
   {
       return [
           Actions\Action::make('regenerateSecret')
               ->action(function (Webhook $record) {
                   $record->secret = Str::random(40);
                   $record->save();
               }),
       ];
   }
   

3. Webhook Widgets: Create Filament widgets to display webhook statistics (e.g., "Webhooks Received Today"):

   // app/Filament/Widgets/WebhookStats.php
   class WebhookStats extends Widget
   {
       protected static string $view = 'filament-webhook-client::widgets.stats';
   
       public function mount(): void
       {
           $this->stats = Webhook::query()
               ->where('created_at', '>=', now()->startOfDay())
               ->count();
       }
   }
   

4. Webhook Event Broadcasting: Broadcast webhook events to Filament’s real-time system (e.g., using Laravel Echo):

   // In a listener
   broadcast(new WebhookReceived($webhook))->toOthers();
   

   Listen for broadcasts in a Filament Livewire component to update the UI dynamically.

Config Quirks

• Secret Management: The package does not store webhook secrets in the database by default (for security). If you need to persist secrets, extend the Webhook model and update the Filament resource accordingly.
• Environment-Specific Config: Publish the config file to override defaults (e.g., webhook_client.secret_length):

  // config/filament-webhook-client.php
  'secret_length' => 64,