## Getting Started

### Minimal Setup
1. **Installation**:
   ```bash
   composer require marjose123/filament-webhook-server
   php artisan vendor:publish --tag="filament-webhook-server-migrations"
   php artisan migrate

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

use Marjose123\FilamentWebhookServer\WebhookPlugin;

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

First Use Case:
- Access the Webhook Server plugin in your Filament admin panel.
- Create a new webhook by selecting a model (e.g., User) and configuring the target URL, events (created, updated, deleted), and payload format (Summary, All, or Custom).

Implementation Patterns

Core Workflow

Model Integration:
- All Eloquent models are automatically available for webhook events.
- Exclude/include specific models via excludedModels()/includeModels() in the plugin configuration:
```
WebhookPlugin::make()
    ->includeModels([\App\Models\Order::class])
    ->excludedModels([\App\Models\Draft::class])
    ->enablePlugin()
```

Payload Customization:

Default Payloads: Use Summary (basic fields) or All (full model data).

Custom Payloads: Implement the Webhookable interface in your model:

use Marjose123\FilamentWebhookServer\Contracts\Webhookable;

class Order extends Model implements Webhookable
{
    public function toWebhookPayload(): array
    {
        return [
            'order_id' => $this->id,
            'total' => $this->amount,
            'customer_email' => $this->user->email,
        ];
    }
}

Event Handling:
- Webhooks trigger on created, updated, and deleted events by default.
- Extend functionality by listening to model events in AppServiceProvider:
```
public function boot()
{
    \App\Models\User::created(function ($user) {
        // Custom logic before webhook dispatch
    });
}
```
API Access:
- Enable API routes for programmatic webhook management:
```
WebhookPlugin::make()->enableApiRoutes()->enablePlugin()
```
- Use the API to create/update webhooks via HTTP requests (e.g., POST /filament/webhooks).
Logging and History:
- Enable webhook logs via keepLogs():
```
WebhookPlugin::make()->keepLogs()->enablePlugin()
```
- View logs in the Webhook History tab within the plugin.

Advanced Patterns

Dynamic Configuration:
- Override default polling intervals (e.g., for high-frequency events):
```
WebhookPlugin::make()->polling(5)->enablePlugin() // Poll every 5 seconds
```
Multi-Tenant Support:
- Use Filament’s clusters to isolate webhook configurations per tenant:
```
WebhookPlugin::make()->cluster('tenant-cluster')->enablePlugin()
```

Testing:

Mock webhook deliveries in tests using Laravel’s Http::fake():

use Illuminate\Support\Facades\Http;

public function test_webhook_delivery()
{
    Http::fake();
    $user = User::create([...]);
    // Assert webhook was called
}

Security:

Validate webhook signatures if using external services (e.g., Stripe):

// In your webhook handler middleware
public function handle(Request $request, Closure $next)
{
    if (!$this->validateSignature($request)) {
        abort(403);
    }
    return $next($request);
}

Gotchas and Tips

Common Pitfalls

Model Registration Issues:
- Problem: Models not appearing in the webhook dropdown.
- Fix: Ensure models are properly namespaced and autoloaded. Re-publish migrations if using custom tables:
```
php artisan vendor:publish --tag="filament-webhook-server-migrations" --force
php artisan migrate:fresh
```
Payload Serialization Errors:
- Problem: Non-serializable data (e.g., relationships) in custom payloads.
- Fix: Explicitly cast or resolve relationships in toWebhookPayload():
```
public function toWebhookPayload(): array
{
    return [
        'user_email' => $this->user?->email ?? null,
    ];
}
```
Event Timing:
- Problem: Webhooks firing out of order or missing events.
- Fix: Use Laravel’s queue for async processing:
```
// In your model observer
public function created(User $user)
{
    dispatch(new DispatchWebhook($user));
}
```
API Route Conflicts:
- Problem: enableApiRoutes() clashing with existing routes.
- Fix: Prefix routes or use middleware to restrict access:
```
WebhookPlugin::make()
    ->enableApiRoutes()
    ->apiPrefix('admin/webhooks')
    ->enablePlugin()
```

Performance:

Problem: Slow response times for webhook deliveries.

Fix: Limit payload size or use Summary format. For bulk operations, batch events:

// In your webhook service
public function dispatchBatch(array $events)
{
    foreach (array_chunk($events, 50) as $chunk) {
        Http::post($url, ['events' => $chunk]);
    }
}

Debugging Tips

Log Webhook Payloads:
- Enable logging via keepLogs() and check the Webhook History tab for raw payloads.
Test Locally:
- Use tools like ngrok to expose local endpoints for testing:
```
ngrok http 8000
```
- Configure webhooks to point to https://your-ngrok-url.ngrok.io/webhook-endpoint.

Validate Signatures:

For security, add signature validation to your webhook endpoint:

public function handleStripeWebhook(Request $request)
{
    $payload = $request->getContent();
    $sigHeader = $request->header('Stripe-Signature');
    if (!\Stripe\Webhook::constructEvent($payload, $sigHeader, config('services.stripe.webhook_secret'))) {
        abort(400);
    }
    // Process event
}

Monitor Failures:

Set up a Laravel Horizon job to retry failed webhooks:

// In your webhook service
public function sendWebhook($url, $payload)
{
    try {
        Http::post($url, $payload);
    } catch (\Exception $e) {
        RetryFailedWebhook::dispatch($url, $payload, $e->getMessage());
    }
}

Extension Points

Custom Pages:

Replace default pages (e.g., for advanced filtering):

WebhookPlugin::make()
    ->customPageUsing(
        webhookPage: \App\Filament\Pages\CustomWebhookPage::class,
        webhookHistoryPage: \App\Filament\Pages\CustomHistoryPage::class
    )
    ->enablePlugin()

Event Extensions:

Add custom events (e.g., published for a Post model):

// In your model observer
public function published(Post $post)
{
    event(new WebhookEvent($post, 'published'));
}

Middleware:

Add middleware to webhook routes for authentication/authorization:

Route::middleware(['auth:sanctum', 'webhook.verify'])->post('/webhooks', [WebhookController::class, 'store']);

Translations:

Extend translations for multilingual support:

// In your language provider
public function boot()
{
    $this->loadTranslationsFrom(__DIR__.'/lang', 'filament-webhook-server');
}

Configuration Quirks

Polling Intervals:
- Set realistic intervals (e.g., 10 seconds) to avoid rate limits or excessive load.
SSL Verification:
- Disable SSL verification for testing only (not production):
```
// In config/filament-webhook-server.php
'webhook' =>
```

Filament Webhook Server Laravel Package