PHPackages                             andreagroferreira/laravel-webhook-owlery - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. andreagroferreira/laravel-webhook-owlery

ActiveLibrary[API Development](/categories/api)

andreagroferreira/laravel-webhook-owlery
========================================

A professional-grade webhook management system for Laravel applications

1.0.2(1y ago)61.2k—0%[1 issues](https://github.com/andreagroferreira/laravel-webhook-owlery/issues)MITPHPPHP ^8.1|^8.2|^8.3|^8.4

Since Mar 13Pushed 1y ago1 watchersCompare

[ Source](https://github.com/andreagroferreira/laravel-webhook-owlery)[ Packagist](https://packagist.org/packages/andreagroferreira/laravel-webhook-owlery)[ RSS](/packages/andreagroferreira-laravel-webhook-owlery/feed)WikiDiscussions v1.0.2 Synced 1mo ago

READMEChangelog (3)Dependencies (16)Versions (7)Used By (0)

Laravel Webhook Owlery
======================

[](#laravel-webhook-owlery)

[![Latest Version on Packagist](https://camo.githubusercontent.com/3ba843ddcd62bb95c6574e2351f2f935cacc6ff7685f98e9346e1cb9e5bcc8fd/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f616e6472656167726f66657272656972612f6c61726176656c2d776562686f6f6b2d6f776c6572792e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/andreagroferreira/laravel-webhook-owlery)[![GitHub Tests Action Status](https://camo.githubusercontent.com/2fd7154355e1c36cab2ca3697dcf9ec477197d01a75ec844d7f5586ec1cdb9c3/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f776f726b666c6f772f7374617475732f616e6472656167726f66657272656972612f6c61726176656c2d776562686f6f6b2d6f776c6572792f72756e2d74657374733f6c6162656c3d7465737473)](https://github.com/andreagroferreira/laravel-webhook-owlery/actions?query=workflow%3Arun-tests+branch%3Amain)[![GitHub Code Style Action Status](https://camo.githubusercontent.com/37a1df78fc4029f087ff0a963c4a5a33dc6804362dd5a9f7b55ebe05e32bfd32/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f776f726b666c6f772f7374617475732f616e6472656167726f66657272656972612f6c61726176656c2d776562686f6f6b2d6f776c6572792f436865636b253230436f64652532305374796c653f6c6162656c3d636f64652532307374796c65)](https://github.com/andreagroferreira/laravel-webhook-owlery/actions?query=workflow%3A%22Check+Code+Style%22+branch%3Amain)[![Total Downloads](https://camo.githubusercontent.com/c8fce2ea1a1f62b1cb913894435df3d5dc0da61caa912dc5c30b93c1f8a9a30f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f616e6472656167726f66657272656972612f6c61726176656c2d776562686f6f6b2d6f776c6572792e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/andreagroferreira/laravel-webhook-owlery)

A robust and feature-complete webhook management system for Laravel applications. Laravel Webhook Owlery handles both sending and receiving webhooks with extensive validation, security, and monitoring capabilities.

✅ **All unit tests passing!** The package is now fully functional and ready for use. Feature tests are currently being refined.

🔍 Features
----------

[](#-features)

- **Complete Webhook Management**: Send and receive webhooks with a unified API
- **Signature Validation**: Support for HMAC, JWT, API key, and Basic Auth validation
- **Circuit Breaker Pattern**: Prevent cascading failures with automatic circuit breaking
- **Retry Mechanism**: Configurable retry strategies for failed webhook deliveries
- **Comprehensive Logging**: Detailed logging of all webhook activities
- **Rate Limiting**: Protect your application from abuse with configurable rate limits
- **Async Processing**: Background processing of webhooks using Laravel's queue system
- **Health Monitoring**: Monitor the health of your webhook system
- **Provider-Specific Handlers**: Built-in support for popular services like Stripe, GitHub, etc.
- **Extensive Configuration**: Highly customizable to fit your application's needs
- **Event-Driven**: Leverage Laravel's event system for webhook lifecycle events
- **Dashboard Ready**: Data structures designed for easy dashboard integration

📥 Installation
--------------

[](#-installation)

You can install the package via composer:

```
composer require andreagroferreira/laravel-webhook-owlery
```

After installing the package, publish the configuration file and migrations:

```
php artisan vendor:publish --provider="WizardingCode\WebhookOwlery\WebhookOwleryServiceProvider"
php artisan migrate
```

### Optional Dependencies

[](#optional-dependencies)

The package supports various signature validation methods. Some of these require additional libraries:

#### JWT Validation

[](#jwt-validation)

To use JWT signature validation, you need to install the Firebase JWT library:

```
composer require firebase/php-jwt
```

Without this library, JWT validation will not be available, and the related tests will be skipped with a "JWT library not installed" message.

⚡ Quick Start
-------------

[](#-quick-start)

### Receiving Webhooks

[](#receiving-webhooks)

1. Configure an endpoint in your `webhook-owlery.php` config file:

```
'endpoints' => [
    'stripe' => [
        'path' => '/webhooks/stripe',
        'secret' => env('STRIPE_WEBHOOK_SECRET'),
        'validator' => 'hmac',
    ],
],
```

2. Create a handler for incoming webhooks:

```
namespace App\Listeners;

use WizardingCode\WebhookOwlery\Events\WebhookReceived;

class ProcessStripeWebhook
{
    public function handle(WebhookReceived $event)
    {
        $payload = $event->payload;
        $event = $payload['type'] ?? null;

        if ($event === 'charge.succeeded') {
            // Process the successful charge
        }
    }
}
```

3. Register your handler in your `EventServiceProvider`:

```
protected $listen = [
    \WizardingCode\WebhookOwlery\Events\WebhookReceived::class => [
        \App\Listeners\ProcessStripeWebhook::class,
    ],
];
```

That's it! Your application is now ready to receive webhooks at `/api/webhooks/stripe`.

### Sending Webhooks

[](#sending-webhooks)

```
use WizardingCode\WebhookOwlery\Facades\Owlery;

// Simple webhook
Owlery::send('user.created', ['user' => $user->toArray()]);

// With specific subscriptions
Owlery::to(['subscription-id-1', 'subscription-id-2'])
      ->send('order.shipped', ['order' => $order->toArray()]);

// With metadata
Owlery::withMetadata(['source' => 'backend', 'initiated_by' => 'system'])
      ->send('payment.failed', ['payment' => $payment->toArray()]);
```

### Command-line Tools

[](#command-line-tools)

The package includes several useful Artisan commands:

```
# Generate a secure webhook secret
php artisan webhook:generate-secret

# List all configured webhook endpoints
php artisan webhook:list-endpoints

# Clean up old webhook data
php artisan webhook:cleanup
```

🔧 Configuration
---------------

[](#-configuration)

### Basic Configuration

[](#basic-configuration)

The configuration file provides extensive options for customizing the behavior of the package:

```
// config/webhook-owlery.php

return [
    'route' => [
        'prefix' => 'api',
        'middleware' => ['api'],
    ],

    'signing' => [
        'default' => 'hmac',
        'hmac' => [
            'algorithm' => 'sha256',
            'header' => 'X-Signature',
        ],
    ],

    'circuit_breaker' => [
        'enabled' => true,
        'threshold' => 5,
        'recovery_time' => 60,
    ],

    // Many more options...
];
```

### Endpoint Configuration

[](#endpoint-configuration)

```
'endpoints' => [
    'stripe' => [
        'path' => '/webhooks/stripe',
        'secret' => env('STRIPE_WEBHOOK_SECRET'),
        'validator' => 'hmac',
        'signature_header' => 'Stripe-Signature',
        'rate_limit' => [
            'enabled' => true,
            'attempts' => 60,
            'decay_minutes' => 1,
        ],
    ],
    'github' => [
        'path' => '/webhooks/github',
        'secret' => env('GITHUB_WEBHOOK_SECRET'),
        'validator' => 'hmac',
        'signature_header' => 'X-Hub-Signature-256',
        'rate_limit' => [
            'enabled' => true,
            'attempts' => 60,
            'decay_minutes' => 1,
        ],
    ],
],
```

### Complete Configuration Example

[](#complete-configuration-example)

```
return [
    /*
    |--------------------------------------------------------------------------
    | Route Configuration
    |--------------------------------------------------------------------------
    |
    | Configure how webhook routes are registered
    |
    */
    'route' => [
        'prefix' => 'api',
        'middleware' => ['api'],
        'name' => 'webhook',
    ],

    /*
    |--------------------------------------------------------------------------
    | Webhook Database Connection
    |--------------------------------------------------------------------------
    |
    | The database connection to use for webhook storage
    |
    */
    'database' => [
        'connection' => null, // null uses default connection
        'table_prefix' => '',
    ],

    /*
    |--------------------------------------------------------------------------
    | Signing Configuration
    |--------------------------------------------------------------------------
    |
    | Configure how webhooks are signed for validation
    |
    */
    'signing' => [
        'default' => 'hmac',
        'hmac' => [
            'algorithm' => 'sha256',
            'header' => 'X-Signature',
        ],
        'jwt' => [
            'algorithm' => 'HS256',
            'header' => 'Authorization',
            'prefix' => 'Bearer ',
            'leeway' => 60, // seconds
        ],
        'api_key' => [
            'header' => 'X-API-Key',
        ],
        'basic_auth' => [
            'header' => 'Authorization',
        ],
    ],

    /*
    |--------------------------------------------------------------------------
    | Outgoing Webhooks
    |--------------------------------------------------------------------------
    |
    | Configure how webhooks are sent from your application
    |
    */
    'outgoing' => [
        'queue' => [
            'connection' => null, // null uses default connection
            'queue' => 'default',
        ],
        'retry' => [
            'default_attempts' => 3,
            'backoff' => [1, 5, 15], // minutes
            'max_attempts' => 10,
        ],
        'timeout' => 5, // seconds
        'concurrency' => 10, // max concurrent webhook dispatches
        'user_agent' => 'Laravel Webhook Owlery',
        'send_timeout' => true, // include request timeout header
    ],

    /*
    |--------------------------------------------------------------------------
    | Incoming Webhooks
    |--------------------------------------------------------------------------
    |
    | Configure how webhooks are received by your application
    |
    */
    'incoming' => [
        'queue' => [
            'connection' => null, // null uses default connection
            'queue' => 'default',
        ],
        'process_async' => true, // process webhooks in the background
        'verify_ssl' => true, // verify SSL certificates for incoming webhooks
    ],

    /*
    |--------------------------------------------------------------------------
    | Monitoring
    |--------------------------------------------------------------------------
    |
    | Monitoring and alerting configuration
    |
    */
    'monitoring' => [
        'log_channel' => null, // null uses default log channel
        'log_level' => 'info',
        'notify_on_failure' => false,
        'alert_threshold' => 5, // alert after 5 failures
        'health_check_interval' => 60, // minutes
    ],

    /*
    |--------------------------------------------------------------------------
    | Circuit Breaker
    |--------------------------------------------------------------------------
    |
    | Configure the circuit breaker for webhook endpoints
    |
    */
    'circuit_breaker' => [
        'enabled' => true,
        'threshold' => 5, // failures before opening
        'recovery_time' => 60, // seconds
        'half_open_allows' => 2, // allowed requests in half-open state
        'storage' => 'redis', // redis or cache
        'cache_prefix' => 'webhook_circuit_',
    ],

    /*
    |--------------------------------------------------------------------------
    | Data Retention
    |--------------------------------------------------------------------------
    |
    | Configure how long webhook data is retained
    |
    */
    'retention' => [
        'successful_webhooks' => 7, // days
        'failed_webhooks' => 30, // days
        'cleanup_interval' => 1440, // minutes (1 day)
    ],

    /*
    |--------------------------------------------------------------------------
    | Rate Limiting
    |--------------------------------------------------------------------------
    |
    | Configure rate limiting for webhook endpoints
    |
    */
    'rate_limiting' => [
        'enabled' => true,
        'default' => [
            'attempts' => 60,
            'decay_minutes' => 1,
        ],
    ],

    /*
    |--------------------------------------------------------------------------
    | Webhook Endpoints
    |--------------------------------------------------------------------------
    |
    | Define pre-configured webhook endpoints for receiving
    |
    */
    'endpoints' => [
        'stripe' => [
            'path' => '/webhooks/stripe',
            'secret' => env('STRIPE_WEBHOOK_SECRET'),
            'validator' => 'hmac',
            'signature_header' => 'Stripe-Signature',
            'rate_limit' => [
                'enabled' => true,
                'attempts' => 60,
                'decay_minutes' => 1,
            ],
        ],
        'github' => [
            'path' => '/webhooks/github',
            'secret' => env('GITHUB_WEBHOOK_SECRET'),
            'validator' => 'hmac',
            'signature_header' => 'X-Hub-Signature-256',
            'rate_limit' => [
                'enabled' => true,
                'attempts' => 60,
                'decay_minutes' => 1,
            ],
        ],
        'shopify' => [
            'path' => '/webhooks/shopify',
            'secret' => env('SHOPIFY_WEBHOOK_SECRET'),
            'validator' => 'hmac',
            'signature_header' => 'X-Shopify-Hmac-Sha256',
            'rate_limit' => [
                'enabled' => true,
                'attempts' => 60,
                'decay_minutes' => 1,
            ],
        ],
    ],
];
```

🛠️ Usage Examples
-----------------

[](#️-usage-examples)

### Managing Webhook Subscriptions

[](#managing-webhook-subscriptions)

```
use WizardingCode\WebhookOwlery\Facades\WebhookRepository;

// Create a new webhook endpoint
$endpoint = WebhookRepository::createEndpoint([
    'url' => 'https://example.com/webhook',
    'description' => 'My application webhook endpoint',
    'secret' => Str::random(64),
    'is_active' => true,
]);

// Create a new webhook subscription
$subscription = WebhookRepository::createSubscription([
    'endpoint_id' => $endpoint->id,
    'event_types' => ['user.created', 'user.updated'],
    'description' => 'User events subscription',
    'is_active' => true,
]);

// Update subscription
WebhookRepository::updateSubscription($subscription->id, [
    'event_types' => ['user.created', 'user.updated', 'user.deleted'],
]);

// Deactivate subscription
WebhookRepository::updateSubscription($subscription->id, [
    'is_active' => false,
]);

// Find endpoints and subscriptions
$activeEndpoints = WebhookRepository::getActiveEndpoints();
$userSubscriptions = WebhookRepository::getSubscriptionsByEventType('user.created');

// Get delivery statistics
$stats = WebhookRepository::getDeliveryStatistics();
```

### Adding a New Provider

[](#adding-a-new-provider)

#### 1. Create a Provider-Specific Request

[](#1-create-a-provider-specific-request)

```
namespace App\Http\Requests\Webhooks;

use WizardingCode\WebhookOwlery\Http\Requests\WebhookReceiveRequest;

class SlackWebhookRequest extends WebhookReceiveRequest
{
    public function rules()
    {
        return [
            'event' => 'required|string',
            'team_id' => 'required|string',
            'api_app_id' => 'required|string',
            'event_id' => 'required|string',
            'event_time' => 'required|integer',
            'payload' => 'required|array',
        ];
    }

    public function getEventType()
    {
        return 'slack.' . ($this->input('event.type') ?? 'unknown');
    }

    public function getPayload()
    {
        return [
            'event' => $this->input('event'),
            'team_id' => $this->input('team_id'),
            'event_id' => $this->input('event_id'),
            'event_time' => $this->input('event_time'),
            'payload' => $this->input('payload'),
        ];
    }
}
```

#### 2. Create a Provider-Specific Validator

[](#2-create-a-provider-specific-validator)

```
namespace App\Validators;

use WizardingCode\WebhookOwlery\Contracts\SignatureValidatorContract;
use Illuminate\Http\Request;

class SlackSignatureValidator implements SignatureValidatorContract
{
    public function validate(Request $request, string $secret): bool
    {
        $signature = $request->header('X-Slack-Signature');
        $timestamp = $request->header('X-Slack-Request-Timestamp');

        // Check if the request is not older than 5 minutes
        $now = time();
        if (abs($now - $timestamp) > 300) {
            return false;
        }

        $payload = $request->getContent();
        $baseString = 'v0:' . $timestamp . ':' . $payload;

        // Compute signature using the secret
        $computedSignature = 'v0=' . hash_hmac('sha256', $baseString, $secret);

        // Compare signatures using constant-time comparison
        return hash_equals($computedSignature, $signature);
    }
}
```

#### 3. Register the Provider in a Service Provider

[](#3-register-the-provider-in-a-service-provider)

```
namespace App\Providers;

use App\Http\Requests\Webhooks\SlackWebhookRequest;
use App\Validators\SlackSignatureValidator;
use WizardingCode\WebhookOwlery\Facades\Owlery;
use WizardingCode\WebhookOwlery\Facades\WebhookReceiver;
use Illuminate\Support\ServiceProvider;

class WebhookServiceProvider extends ServiceProvider
{
    public function boot()
    {
        // Register the signature validator
        Owlery::validator('slack', SlackSignatureValidator::class);

        // Register the request handler
        WebhookReceiver::registerProvider('slack', SlackWebhookRequest::class);
    }
}
```

#### 4. Add Configuration for the Provider

[](#4-add-configuration-for-the-provider)

Update your `config/webhook-owlery.php` file:

```
'endpoints' => [
    // ... other providers
    'slack' => [
        'path' => '/webhooks/slack',
        'secret' => env('SLACK_SIGNING_SECRET'),
        'validator' => 'slack',
        'signature_header' => 'X-Slack-Signature',
        'rate_limit' => [
            'enabled' => true,
            'attempts' => 60,
            'decay_minutes' => 1,
        ],
    ],
],
```

#### 5. Create an Event Listener for the Provider

[](#5-create-an-event-listener-for-the-provider)

```
namespace App\Listeners;

use WizardingCode\WebhookOwlery\Events\WebhookReceived;
use Illuminate\Support\Facades\Log;

class HandleSlackWebhooks
{
    public function handle(WebhookReceived $event)
    {
        if ($event->endpoint !== 'slack') {
            return;
        }

        $payload = $event->payload;
        $eventType = $payload['event']['type'] ?? 'unknown';

        Log::info('Received Slack webhook', [
            'event_type' => $eventType,
            'team_id' => $payload['team_id'],
        ]);

        // Process different Slack event types
        switch ($eventType) {
            case 'message':
                $this->handleMessage($payload);
                break;

            case 'app_mention':
                $this->handleAppMention($payload);
                break;

            // Handle other event types
        }
    }

    protected function handleMessage(array $payload)
    {
        $message = $payload['event']['text'] ?? '';
        $user = $payload['event']['user'] ?? '';
        $channel = $payload['event']['channel'] ?? '';

        // Process the message
    }

    protected function handleAppMention(array $payload)
    {
        $mention = $payload['event']['text'] ?? '';
        $user = $payload['event']['user'] ?? '';
        $channel = $payload['event']['channel'] ?? '';

        // Process the app mention
    }
}
```

#### 6. Register the Event Listener

[](#6-register-the-event-listener)

In your `EventServiceProvider.php`:

```
protected $listen = [
    \WizardingCode\WebhookOwlery\Events\WebhookReceived::class => [
        // ... other listeners
        \App\Listeners\HandleSlackWebhooks::class,
    ],
];
```

### Custom Signature Validation

[](#custom-signature-validation)

```
// Create a custom validator
namespace App\Validators;

use WizardingCode\WebhookOwlery\Contracts\SignatureValidatorContract;
use Illuminate\Http\Request;

class CustomValidator implements SignatureValidatorContract
{
    public function validate(Request $request, string $secret): bool
    {
        $signature = $request->header('X-Custom-Signature');
        $payload = $request->getContent();

        // Your custom validation logic
        $expectedSignature = hash_hmac('sha512', $payload, $secret);

        return hash_equals($expectedSignature, $signature);
    }
}
```

Register your custom validator in a service provider:

```
use WizardingCode\WebhookOwlery\Facades\Owlery;

public function boot()
{
    Owlery::validator('custom', \App\Validators\CustomValidator::class);
}
```

### Advanced Webhook Dispatch

[](#advanced-webhook-dispatch)

```
use WizardingCode\WebhookOwlery\Facades\Owlery;

// With custom retry strategy
Owlery::withRetry([
    'attempts' => 5,
    'backoff' => [1, 5, 15, 30, 60], // minutes
])
->send('invoice.paid', ['invoice' => $invoice->toArray()]);

// With conditional recipients
$subscribers = $company->partners->pluck('webhook_subscription_id')->toArray();

Owlery::to($subscribers)
      ->withMetadata([
          'company_id' => $company->id,
          'importance' => 'high',
      ])
      ->send('product.released', ['product' => $product->toArray()]);

// With conditional dispatching
Owlery::when($order->total > 1000)
      ->send('order.high_value', ['order' => $order->toArray()]);

// With custom headers
Owlery::withHeaders([
    'X-Custom-Header' => 'custom-value',
    'X-Source-System' => 'inventory',
])
->send('inventory.updated', ['product' => $product->toArray()]);

// With batch sending
Owlery::batch([
    ['event' => 'user.created', 'payload' => ['user' => $user->toArray()]],
    ['event' => 'profile.created', 'payload' => ['profile' => $profile->toArray()]],
    ['event' => 'preferences.set', 'payload' => ['preferences' => $preferences]],
])
->send();
```

### Real-World Example: E-commerce Order Flow

[](#real-world-example-e-commerce-order-flow)

```
namespace App\Services;

use App\Models\Order;
use WizardingCode\WebhookOwlery\Facades\Owlery;

class OrderProcessor
{
    public function processOrder(Order $order)
    {
        // Process the order...

        // Notify systems about new order
        Owlery::send('order.created', [
            'order' => [
                'id' => $order->id,
                'reference' => $order->reference,
                'total' => $order->total,
                'currency' => $order->currency,
                'status' => $order->status,
                'created_at' => $order->created_at,
            ],
            'customer' => [
                'id' => $order->customer->id,
                'email' => $order->customer->email,
            ],
            'items' => $order->items->map(function ($item) {
                return [
                    'product_id' => $item->product_id,
                    'quantity' => $item->quantity,
                    'price' => $item->price,
                ];
            })->toArray(),
        ]);

        // If it's a large order, notify VIP system with high priority
        if ($order->total > 1000) {
            Owlery::to(['vip-orders-subscription'])
                  ->withMetadata([
                      'priority' => 'high',
                      'department' => 'vip-sales',
                  ])
                  ->withRetry([
                      'attempts' => 10,
                      'backoff' => [1, 1, 5, 5, 10, 15, 30, 60, 120, 240],
                  ])
                  ->send('order.vip', [
                      'order' => $order->toArray(),
                      'customer' => $order->customer->toArray(),
                      'sales_rep' => $order->salesRepresentative->toArray(),
                  ]);
        }
    }

    public function fulfillOrder(Order $order)
    {
        // Process fulfillment...

        // Notify systems about fulfilled order
        Owlery::send('order.fulfilled', [
            'order_id' => $order->id,
            'fulfillment' => [
                'tracking_number' => $order->tracking_number,
                'carrier' => $order->shipping_carrier,
                'fulfilled_at' => now(),
            ],
        ]);
    }
}
```

### Real-World Example: SaaS User Onboarding

[](#real-world-example-saas-user-onboarding)

```
namespace App\Services;

use App\Models\User;
use App\Models\Team;
use WizardingCode\WebhookOwlery\Facades\Owlery;

class UserOnboardingService
{
    public function createUser(array $userData)
    {
        // Create the user
        $user = User::create([
            'name' => $userData['name'],
            'email' => $userData['email'],
            'password' => bcrypt($userData['password']),
        ]);

        // Send webhook for user creation
        Owlery::send('user.created', [
            'user' => [
                'id' => $user->id,
                'name' => $user->name,
                'email' => $user->email,
                'created_at' => $user->created_at->toIso8601String(),
            ],
        ]);

        return $user;
    }

    public function createTeam(User $user, array $teamData)
    {
        // Create the team
        $team = Team::create([
            'name' => $teamData['name'],
            'owner_id' => $user->id,
        ]);

        // Associate user with team
        $user->teams()->attach($team->id, ['role' => 'owner']);

        // Send webhook for team creation
        Owlery::send('team.created', [
            'team' => [
                'id' => $team->id,
                'name' => $team->name,
                'created_at' => $team->created_at->toIso8601String(),
            ],
            'owner' => [
                'id' => $user->id,
                'name' => $user->name,
                'email' => $user->email,
            ],
        ]);

        // If this is an enterprise team, notify the sales department
        if (isset($teamData['enterprise']) && $teamData['enterprise']) {
            Owlery::to(['sales-subscription'])
                  ->withMetadata([
                      'priority' => 'high',
                      'department' => 'enterprise-sales',
                  ])
                  ->send('team.enterprise_created', [
                      'team' => $team->toArray(),
                      'owner' => $user->toArray(),
                      'plan' => $teamData['plan'] ?? 'free',
                  ]);
        }

        return $team;
    }

    public function completeOnboarding(User $user, Team $team)
    {
        // Update user and team status
        $user->update(['onboarded_at' => now()]);
        $team->update(['setup_completed_at' => now()]);

        // Send webhook for completed onboarding
        Owlery::send('onboarding.completed', [
            'user' => [
                'id' => $user->id,
                'name' => $user->name,
                'email' => $user->email,
            ],
            'team' => [
                'id' => $team->id,
                'name' => $team->name,
            ],
            'completed_at' => now()->toIso8601String(),
        ]);

        // Notify multiple systems about the completed onboarding
        Owlery::to(['marketing-subscription', 'customer-success-subscription'])
              ->withMetadata([
                  'source' => 'onboarding-service',
                  'completion_time' => round((now()->timestamp - $user->created_at->timestamp) / 60), // minutes
              ])
              ->send('user.onboarded', [
                  'user' => $user->toArray(),
                  'team' => $team->toArray(),
                  'journey' => [
                      'started_at' => $user->created_at->toIso8601String(),
                      'completed_at' => now()->toIso8601String(),
                      'duration_minutes' => round((now()->timestamp - $user->created_at->timestamp) / 60),
                  ],
              ]);
    }
}
```

### Handling Incoming Webhooks: Stripe Example

[](#handling-incoming-webhooks-stripe-example)

```
namespace App\Listeners;

use WizardingCode\WebhookOwlery\Events\WebhookReceived;
use App\Models\Payment;
use App\Services\SubscriptionService;
use Illuminate\Support\Facades\Log;

class HandleStripeWebhooks
{
    protected $subscriptionService;

    public function __construct(SubscriptionService $subscriptionService)
    {
        $this->subscriptionService = $subscriptionService;
    }

    public function handle(WebhookReceived $event)
    {
        if ($event->endpoint !== 'stripe') {
            return;
        }

        $payload = $event->payload;
        $stripeEvent = $payload['type'] ?? null;

        switch ($stripeEvent) {
            case 'invoice.payment_succeeded':
                $this->handleInvoicePaymentSucceeded($payload);
                break;

            case 'customer.subscription.deleted':
                $this->handleSubscriptionCancelled($payload);
                break;

            case 'payment_intent.payment_failed':
                $this->handlePaymentFailed($payload);
                break;

            default:
                Log::info('Unhandled Stripe webhook', ['type' => $stripeEvent]);
        }
    }

    protected function handleInvoicePaymentSucceeded(array $payload)
    {
        $invoiceData = $payload['data']['object'];
        $customerId = $invoiceData['customer'];
        $subscriptionId = $invoiceData['subscription'];

        // Record the payment
        Payment::create([
            'stripe_customer_id' => $customerId,
            'stripe_subscription_id' => $subscriptionId,
            'amount' => $invoiceData['amount_paid'],
            'currency' => $invoiceData['currency'],
            'invoice_id' => $invoiceData['id'],
            'status' => 'succeeded',
        ]);

        // Update the subscription
        $this->subscriptionService->extendSubscription($subscriptionId);
    }

    protected function handleSubscriptionCancelled(array $payload)
    {
        $subscriptionData = $payload['data']['object'];
        $subscriptionId = $subscriptionData['id'];

        $this->subscriptionService->cancelSubscription($subscriptionId);
    }

    protected function handlePaymentFailed(array $payload)
    {
        $paymentData = $payload['data']['object'];
        $customerId = $paymentData['customer'];

        // Record the failed payment
        Payment::create([
            'stripe_customer_id' => $customerId,
            'amount' => $paymentData['amount'],
            'currency' => $paymentData['currency'],
            'payment_intent_id' => $paymentData['id'],
            'status' => 'failed',
            'error_message' => $paymentData['last_payment_error']['message'] ?? null,
        ]);

        // Notify customer about failed payment
        $this->subscriptionService->notifyPaymentFailure($customerId);
    }
}
```

### Building a Customized Webhook Dispatcher

[](#building-a-customized-webhook-dispatcher)

This example shows how to extend the basic functionality with a specialized webhook dispatcher:

```
namespace App\Services;

use WizardingCode\WebhookOwlery\Facades\Owlery;
use WizardingCode\WebhookOwlery\Facades\WebhookRepository;
use Illuminate\Support\Collection;

class EnhancedWebhookDispatcher
{
    /**
     * Send webhooks to subscriptions based on tags
     */
    public function sendToTags(array $tags, string $eventType, array $payload, array $options = [])
    {
        // Find all subscriptions with the given tags
        $subscriptions = WebhookRepository::getSubscriptionsByTags($tags);

        if ($subscriptions->isEmpty()) {
            return;
        }

        return $this->dispatchToSubscriptions($subscriptions, $eventType, $payload, $options);
    }

    /**
     * Send webhooks to a subset of subscriptions based on a filter
     */
    public function sendToFiltered(callable $filter, string $eventType, array $payload, array $options = [])
    {
        // Get all subscriptions for the event type
        $allSubscriptions = WebhookRepository::getSubscriptionsByEventType($eventType);

        // Filter the subscriptions
        $filteredSubscriptions = $allSubscriptions->filter($filter);

        if ($filteredSubscriptions->isEmpty()) {
            return;
        }

        return $this->dispatchToSubscriptions($filteredSubscriptions, $eventType, $payload, $options);
    }

    /**
     * Send feature announcements to all active subscriptions
     */
    public function announceFeature(string $featureName, array $featureDetails, array $options = [])
    {
        // Prepare the payload
        $payload = [
            'feature' => $featureName,
            'details' => $featureDetails,
            'announced_at' => now()->toIso8601String(),
        ];

        // Set default options
        $options = array_merge([
            'retry' => [
                'attempts' => 5,
                'backoff' => [5, 15, 30, 60, 120], // minutes
            ],
            'metadata' => [
                'importance' => 'announcement',
                'source' => 'product-team',
            ],
        ], $options);

        // Get all active subscriptions
        $activeSubscriptions = WebhookRepository::getActiveSubscriptions();

        return $this->dispatchToSubscriptions($activeSubscriptions, 'feature.announced', $payload, $options);
    }

    /**
     * Dispatch webhooks to multiple subscriptions with options
     */
    protected function dispatchToSubscriptions(Collection $subscriptions, string $eventType, array $payload, array $options = [])
    {
        $subscriptionIds = $subscriptions->pluck('id')->toArray();

        $dispatcher = Owlery::to($subscriptionIds);

        // Apply retry strategy if provided
        if (isset($options['retry'])) {
            $dispatcher->withRetry($options['retry']);
        }

        // Apply metadata if provided
        if (isset($options['metadata'])) {
            $dispatcher->withMetadata($options['metadata']);
        }

        // Apply headers if provided
        if (isset($options['headers'])) {
            $dispatcher->withHeaders($options['headers']);
        }

        return $dispatcher->send($eventType, $payload);
    }
}
```

Usage of the custom dispatcher:

```
// Send to subscriptions with specific tags
$dispatcher = new EnhancedWebhookDispatcher();
$dispatcher->sendToTags(['billing', 'finance'], 'invoice.paid', [
    'invoice' => $invoice->toArray(),
]);

// Send to filtered subscriptions
$dispatcher->sendToFiltered(function ($subscription) use ($user) {
    // Only send to subscriptions belonging to the user's organization
    return $subscription->organization_id === $user->organization_id;
}, 'project.created', [
    'project' => $project->toArray(),
]);

// Announce a new feature
$dispatcher->announceFeature('Advanced Analytics', [
    'name' => 'Advanced Analytics',
    'description' => 'Track detailed metrics with our new analytics dashboard',
    'documentation_url' => 'https://docs.example.com/advanced-analytics',
    'available_from' => now()->addDays(7)->toIso8601String(),
]);
```

🧪 Testing
---------

[](#-testing)

The package ships with a comprehensive test suite using Pest PHP.

### Running Unit Tests

[](#running-unit-tests)

To run the unit tests (all currently passing):

```
composer test
# or specifically
vendor/bin/pest --group=unit
```

Output:

```
PASS  Tests\Unit\CircuitBreakerTest
PASS  Tests\Unit\HmacSignatureValidatorTest
PASS  Tests\Unit\OwleryTest
PASS  Tests\Unit\Validators\ApiKeyValidatorTest
PASS  Tests\Unit\Validators\BasicAuthValidatorTest
WARN  Tests\Unit\Validators\JwtSignatureValidatorTest (Skipped - JWT library not installed)
PASS  Tests\Unit\WebhookDispatcherTest
PASS  Tests\Unit\WebhookRepositoryTest

Tests:  4 skipped, 33 passed (70 assertions)

```

> **Note:** Feature tests are currently being refined and will be available in a future release. The core functionality is fully tested with unit tests.

### GitHub Actions CI

[](#github-actions-ci)

The CI pipeline is configured to run all unit tests against multiple PHP and Laravel versions. Feature tests are excluded from the CI pipeline until they are fully stabilized in a future release.

> **Note:** The skipped tests for JWT validation will automatically run if you install the Firebase JWT library with `composer require firebase/php-jwt`. This is expected behavior as the JWT functionality is considered optional.

### Writing Tests for Webhook Handling

[](#writing-tests-for-webhook-handling)

```
namespace Tests\Feature;

use WizardingCode\WebhookOwlery\Facades\Owlery;
use WizardingCode\WebhookOwlery\Events\WebhookReceived;
use WizardingCode\WebhookOwlery\Facades\WebhookRepository;
use Illuminate\Support\Facades\Event;
use Illuminate\Support\Facades\Http;
use Tests\TestCase;

class WebhookTest extends TestCase
{
    /** @test */
    public function it_can_receive_and_validate_webhooks()
    {
        Event::fake([WebhookReceived::class]);

        $payload = [
            'id' => 'evt_123456',
            'type' => 'payment_intent.succeeded',
            'data' => [
                'object' => [
                    'id' => 'pi_123456',
                    'amount' => 1500,
                    'currency' => 'usd',
                ],
            ],
        ];

        // Generate a signature for the webhook
        $secret = config('webhook-owlery.endpoints.stripe.secret');
        $timestamp = time();
        $signature = $timestamp . '.' . hash_hmac('sha256', $timestamp . '.' . json_encode($payload), $secret);

        // Make the request
        $response = $this->postJson('/api/webhooks/stripe', $payload, [
            'Stripe-Signature' => $signature,
        ]);

        $response->assertStatus(200);

        // Assert the event was dispatched
        Event::assertDispatched(WebhookReceived::class, function ($event) {
            return $event->endpoint === 'stripe' &&
                   $event->payload['type'] === 'payment_intent.succeeded';
        });
    }

    /** @test */
    public function it_rejects_webhooks_with_invalid_signatures()
    {
        $payload = [
            'id' => 'evt_123456',
            'type' => 'payment_intent.succeeded',
        ];

        // Make the request with an invalid signature
        $response = $this->postJson('/api/webhooks/stripe', $payload, [
            'Stripe-Signature' => 'invalid-signature',
        ]);

        $response->assertStatus(403);
    }

    /** @test */
    public function it_can_send_webhooks()
    {
        // Mock the HTTP client
        Http::fake([
            '*' => Http::response(['success' => true], 200),
        ]);

        // Create a test endpoint
        $endpoint = WebhookRepository::createEndpoint([
            'url' => 'https://example.com/webhook',
            'secret' => 'test-secret',
            'is_active' => true,
            'name' => 'Test Endpoint',
            'source' => 'testing',
        ]);

        // Create a test subscription
        $subscription = WebhookRepository::createSubscription([
            'endpoint_id' => $endpoint->id,
            'event_types' => ['test.event'],
            'is_active' => true,
        ]);

        // Send the webhook
        $result = Owlery::to([$subscription->id])
                        ->send('test.event', ['message' => 'Hello, world!']);

        // Assert the webhook was sent
        Http::assertSent(function ($request) {
            return $request->url() === 'https://example.com/webhook' &&
                   $request->hasHeader('X-Signature') &&
                   json_decode($request->body(), true)['event'] === 'test.event';
        });
    }
}
```

⚙️ Artisan Commands
-------------------

[](#️-artisan-commands)

Laravel Webhook Owlery comes with several helpful Artisan commands:

### Generate Webhook Secret

[](#generate-webhook-secret)

```
php artisan webhook:generate-secret
```

Generates a secure random string to use as a webhook secret. Options include:

```
# Generate with custom length
php artisan webhook:generate-secret --length=64

# Generate and copy to clipboard
php artisan webhook:generate-secret --copy

# Generate with custom prefix
php artisan webhook:generate-secret --prefix="whsec_"
```

### List Webhook Endpoints

[](#list-webhook-endpoints)

```
php artisan webhook:list-endpoints
```

Lists all configured webhook endpoints with their status. Available filters:

```
# Show only active endpoints
php artisan webhook:list-endpoints --active

# Show only inactive endpoints
php artisan webhook:list-endpoints --inactive

# Show detailed information
php artisan webhook:list-endpoints --details
```

### Cleanup Webhooks

[](#cleanup-webhooks)

```
php artisan webhook:cleanup
```

Removes old webhook data based on your retention settings. Options include:

```
# Custom retention period
php artisan webhook:cleanup --days=60

# Specific retention periods for different types
php artisan webhook:cleanup --success-days=7 --failed-days=30

# Dry run (shows what would be deleted without actually deleting)
php artisan webhook:cleanup --dry-run
```

📊 Dashboard Integration
-----------------------

[](#-dashboard-integration)

Laravel Webhook Owlery is designed to be dashboard-friendly. Its data structures make it easy to build monitoring dashboards with information on:

- Webhook delivery success/failure rates
- Latency metrics
- Error patterns
- Most active subscriptions/endpoints
- Circuit breaker status

### Example Dashboard Queries

[](#example-dashboard-queries)

```
// Get webhook delivery summary
$summary = DB::table('webhook_deliveries')
    ->select(
        DB::raw('DATE(created_at) as date'),
        DB::raw('COUNT(*) as total'),
        DB::raw('SUM(CASE WHEN status = "success" THEN 1 ELSE 0 END) as successful'),
        DB::raw('SUM(CASE WHEN status = "failed" THEN 1 ELSE 0 END) as failed'),
        DB::raw('AVG(CASE WHEN status = "success" THEN response_time ELSE NULL END) as avg_response_time')
    )
    ->where('created_at', '>=', now()->subDays(30))
    ->groupBy('date')
    ->orderBy('date', 'desc')
    ->get();

// Get most frequent webhook events
$topEvents = DB::table('webhook_events')
    ->select('type', DB::raw('COUNT(*) as count'))
    ->where('created_at', '>=', now()->subDays(30))
    ->groupBy('type')
    ->orderBy('count', 'desc')
    ->limit(10)
    ->get();

// Get endpoints with most failures
$problematicEndpoints = DB::table('webhook_deliveries')
    ->join('webhook_subscriptions', 'webhook_deliveries.subscription_id', '=', 'webhook_subscriptions.id')
    ->join('webhook_endpoints', 'webhook_subscriptions.endpoint_id', '=', 'webhook_endpoints.id')
    ->select(
        'webhook_endpoints.url',
        DB::raw('COUNT(*) as total_attempts'),
        DB::raw('SUM(CASE WHEN webhook_deliveries.status = "failed" THEN 1 ELSE 0 END) as failed'),
        DB::raw('(SUM(CASE WHEN webhook_deliveries.status = "failed" THEN 1 ELSE 0 END) / COUNT(*)) * 100 as failure_rate')
    )
    ->where('webhook_deliveries.created_at', '>=', now()->subDays(30))
    ->groupBy('webhook_endpoints.url')
    ->having('total_attempts', '>', 10)
    ->orderBy('failure_rate', 'desc')
    ->limit(10)
    ->get();
```

🔒 Security
----------

[](#-security)

Webhook Owlery takes security seriously:

- All secrets are stored encrypted in the database
- Signatures are validated using constant-time comparison to prevent timing attacks
- Rate limiting protects against abuse
- Circuit breaker prevents cascading failures
- Detailed logging for audit trails

### Signature Validation Methods

[](#signature-validation-methods)

The package supports multiple signature validation methods:

1. **HMAC Signatures** - The default and most common method (no additional dependencies required)
2. **JWT Validation** - Requires the Firebase JWT library (`composer require firebase/php-jwt`)
3. **API Key Validation** - Simple validation with API keys (no additional dependencies required)
4. **Basic Auth Validation** - Username/password validation (no additional dependencies required)
5. **Custom Validators** - Create your own validators for specific providers

### Security Best Practices

[](#security-best-practices)

1. **Always use HTTPS** for webhook endpoints
2. **Rotate webhook secrets** periodically
3. **Use the built-in rate limiting** to prevent abuse
4. **Monitor webhook deliveries** for unusual patterns
5. **Use the circuit breaker** to prevent cascading failures
6. **Validate all incoming webhook data** before processing
7. **Store webhook secrets securely** using environment variables
8. **Choose the appropriate validation method** based on your security requirements

📖 Changelog
-----------

[](#-changelog)

Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.

🤝 Contributing
--------------

[](#-contributing)

Please see [CONTRIBUTING](CONTRIBUTING.md) for details.

🔐 Security Vulnerabilities
--------------------------

[](#-security-vulnerabilities)

If you discover any security vulnerabilities, please follow our [security policy](SECURITY.md).

📄 License
---------

[](#-license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

🚀 Development Status
--------------------

[](#-development-status)

The package is now fully functional with all tests passing. The following components have been implemented:

- ✅ Core webhook sending and receiving infrastructure
- ✅ Multiple signature validators (HMAC, JWT, API Key, Basic Auth)
- ✅ Circuit breaker pattern for reliable webhook delivery
- ✅ Webhook event storage and logging
- ✅ Administrative commands for managing webhooks
- ✅ Comprehensive test suite

### Release Checklist

[](#release-checklist)

The package is ready for a v1.0.0 production release! All of the following have been completed:

- ✅ All unit tests passing (33 tests with 70 assertions)
- ✅ Documentation completed with comprehensive examples
- ✅ Code style configured with Laravel Pint
- ✅ Static analysis set up with PHPStan
- ✅ Security policy and contribution guidelines
- ✅ MIT License
- ✅ Package infrastructure (composer.json, .gitattributes, etc.)
- ⏳ Feature tests to be enhanced in future updates

###  Health Score

37

—

LowBetter than 83% of packages

Maintenance41

Moderate activity, may be stable

Popularity25

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity59

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~1 days

Total

5

Last Release

427d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/56b076ca26a29dde8c2946bea9a1eeea0ea87e5019037a67766a39642aa71862?d=identicon)[andreagroferreira.af](/maintainers/andreagroferreira.af)

---

Top Contributors

[![andreagroferreira](https://avatars.githubusercontent.com/u/35269365?v=4)](https://github.com/andreagroferreira "andreagroferreira (5 commits)")

---

Tags

apilaraveleventswebhookcallbacksintegrationsowlery

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

Type Coverage Yes

### Embed Badge

![Health badge](/badges/andreagroferreira-laravel-webhook-owlery/health.svg)

```
[![Health](https://phpackages.com/badges/andreagroferreira-laravel-webhook-owlery/health.svg)](https://phpackages.com/packages/andreagroferreira-laravel-webhook-owlery)
```

###  Alternatives

[roots/acorn

Framework for Roots WordPress projects built with Laravel components.

9682.1M97](/packages/roots-acorn)[laravel/pulse

Laravel Pulse is a real-time application performance monitoring tool and dashboard for your Laravel application.

1.7k12.1M99](/packages/laravel-pulse)[essa/api-tool-kit

set of tools to build an api with laravel

52680.5k](/packages/essa-api-tool-kit)[flat3/lodata

OData v4.01 Producer for Laravel

96320.9k](/packages/flat3-lodata)[simplestats-io/laravel-client

Client for SimpleStats!

4515.5k](/packages/simplestats-io-laravel-client)[ryangjchandler/bearer

Minimalistic token-based authentication for Laravel API endpoints.

8129.8k](/packages/ryangjchandler-bearer)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)