Getting Started

Minimal Setup

Prerequisites: Ensure you have Spatie Webhook Client installed and configured in your Laravel project.

Installation:

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

Publish Config:
```
php artisan vendor:publish --tag="filament-webhook-client-config"
```
(Optional: Publish translations with --tag="filament-webhook-client-translations")

Register Plugin: Add the plugin to your Filament panel in app/Providers/Filament/AdminPanelProvider.php:

use Tapp\FilamentWebhookClient\FilamentWebhookClientPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            FilamentWebhookClientPlugin::make(),
        ]);
}

First Use Case: Access the /admin/webhook-calls route in your Filament panel to view and manage webhook calls. The resource provides a pre-built UI for listing, filtering, and inspecting webhook payloads.

Implementation Patterns

Core Workflows

Webhook Call Management:
- List View: Filter webhook calls by status (success/failure), timestamp, or endpoint.
- Detail View: Inspect raw payloads, headers, and metadata in a formatted JSON display.
- Actions: Use Filament’s built-in actions (e.g., bulk delete, export) via the resource’s actions() method.

Policy Integration: Extend the default WebhookCallPolicy to restrict access:

// config/filament-webhook-client.php
'policies' => [
    'webhook-call' => App\Policies\CustomWebhookCallPolicy::class,
],

Define custom policies in app/Policies/CustomWebhookCallPolicy.php:

public function viewAny(User $user): bool
{
    return $user->hasRole('webhook_admin');
}

Customization: Override the resource class to add fields or modify behavior:

// app/Providers/Filament/AdminPanelProvider.php
FilamentWebhookClientPlugin::make()
    ->resourceClass(CustomWebhookCallResource::class),

Example CustomWebhookCallResource:

namespace App\Filament\Resources;

use Tapp\FilamentWebhookClient\Resources\WebhookCallResource as BaseResource;

class CustomWebhookCallResource extends BaseResource
{
    protected static ?string $model = \Spatie\WebhookClient\Models\WebhookCall::class;

    public static function table(Table $table): Table
    {
        return $table
            ->columns([
                // Add custom columns
                Tables\Columns\TextColumn::make('custom_field')
                    ->label('Custom Label'),
            ]);
    }
}

Navigation: Customize the plugin’s navigation position or icon in the config:

'navigation' => [
    'sort' => 2, // Adjust position
    'icon' => 'heroicon-o-bell-alert', // Use a different icon
],

Testing: Test webhook interactions using Spatie’s testing tools alongside Filament’s UI:

use Spatie\WebhookClient\WebhookCall;

public function test_webhook_call_management()
{
    $call = WebhookCall::factory()->create();
    $this->actingAs($user)
         ->get('/admin/webhook-calls')
         ->assertSee($call->id);
}

Gotchas and Tips

Pitfalls

Missing Spatie Webhook Client: The package requires Spatie’s laravel-webhook-client to be installed. Forgetting this will cause runtime errors.
Policy Conflicts: Overriding the default policy without updating the config will result in no permissions being applied. Always update the policies array in filament-webhook-client.php when extending policies.
JSON Formatting: The package displays payloads as formatted JSON by default. For large payloads, this may impact performance. Consider adding a TextColumn with truncation for better UX:
```
TextColumn::make('payload')
    ->limit(200)
    ->toggleable(isToggledHiddenByDefault: true),
```
Filament Version Mismatch: Ensure compatibility between Filament versions (e.g., v4.x of this package requires Filament 4.x/5.x). Mixing versions may break the UI or functionality.
Translation Keys: Custom translations require publishing the translations file and updating language files. Default keys are prefixed with filament-webhook-client::.

Debugging Tips

Log Webhook Calls: Enable Spatie’s logging to debug webhook processing:
```
'logging' => true, // In config/webhook-client.php
```
Check Resource Registration: Verify the plugin is registered in panel()->plugins(). Missing registration will hide the resource entirely.
Clear Filament Cache: After customizing the resource or config, clear Filament’s cache:
```
php artisan filament:cache-reset
```

Payload Inspection: Use Laravel’s dd() or dump() in a custom resource method to inspect payloads during development:

public static function getPages(): array
{
    $pages = parent::getPages();
    $pages['view'] = fn (Page $page) => $page
        ->modifyQueryUsing(fn (QueryBuilder $query) => $query->limit(1))
        ->header(fn (PageHeader $header) => $header
            ->description(fn (WebhookCall $record) => dd($record->payload)));
    return $pages;
}

Extension Points

Custom Actions: Add bulk actions or custom buttons to the resource table:

public static function table(Table $table): Table
{
    return $table
        ->actions([
            Action::make('retry')
                ->action(fn (WebhookCall $record) => $record->retry())
                ->visible(fn (WebhookCall $record) => $record->failed()),
        ]);
}

Webhook Endpoint Management: Extend the package to manage webhook endpoints (e.g., using Spatie’s Webhook model) by creating a separate resource and linking it to the plugin.

Real-Time Updates: Use Filament’s livewire components to add real-time webhook status updates (e.g., polling the API for new calls):

use Livewire\Component;

class WebhookCallLivewire extends Component
{
    public function refreshCalls()
    {
        $this->dispatch('refreshWebhookCalls');
    }
}

Export Functionality: Add CSV/Excel exports for webhook logs:

public static function table(Table $table): Table
{
    return $table
        ->actions([
            Tables\Actions\ExportAction::make(),
        ]);
}

Dark Mode Support: Ensure your customizations respect Filament’s dark mode by using Filament’s built-in styling classes (e.g., dark:bg-gray-800).

Filament Webhook Client Laravel Package