README

Stripe Watcher

Package allowing you to inspect the stripe webhooks payload and result

Installation

You can install the package via Composer:

composer require ivalin-venkov/stripe-watcher

Stripe Watcher is designed to work alongside Stripe's PHP SDK. The package does not verify webhook signatures itself; verify the request in your existing webhook integration before the capture middleware runs. Composer will suggest stripe/stripe-php, but it is not a required dependency because verification may also be handled by Laravel Cashier or custom application code.

You may publish all of the package's resources at once:

php artisan vendor:publish --tag="stripe-watcher"

Or, you may publish each resource individually:

Publishing the Configuration File

php artisan vendor:publish --tag="stripe-watcher-config"

Publishing and Running the Migrations

php artisan vendor:publish --tag="stripe-watcher-migrations"
php artisan migrate

Publishing the Views

php artisan vendor:publish --tag="stripe-watcher-views"

Publishing the Translations

php artisan vendor:publish --tag="stripe-watcher-lang"

Publishing the Public Assets

php artisan vendor:publish --tag="stripe-watcher-assets"

Usage

The dashboard is disabled by default. Enable it explicitly in the published configuration file:

'enabled' => true,

The dashboard route is protected with Laravel authorization. Define the configured ability in the application, for example:

use Illuminate\Support\Facades\Gate;

Gate::define('viewStripeWatcher', function (User $user): bool {
    return $user->is_admin;
});

The dashboard uses the web, auth, and can:viewStripeWatcher middleware by default. These middleware, the route prefix, and the ability name can be changed in config/stripe-watcher.php.

The package provides a stripe_watcher_webhooks table and model for webhook capture. Publish and run the package migration when you are ready to enable storage. Attach the capture middleware to the application's existing Stripe webhook route; the package does not create a proxy endpoint:

use StripeWatcher\StripeWatcher\Http\Middleware\CaptureWebhook;

Route::post('/stripe/webhook', WebhookController::class)
    ->middleware(CaptureWebhook::class);

Request and response headers and JSON payloads are redacted at the model boundary before storage. Configure the storage table through storage.table and sanitization through the redaction section of config/stripe-watcher.php. The package migration always creates and rolls back stripe_watcher_webhooks; if you configure a custom storage table, create its migration separately. Redaction fails closed: disabling it omits bodies, headers, and payloads rather than storing them unredacted. Invalid or non-JSON bodies are also omitted.

Request URLs are omitted to avoid persisting secrets embedded in URL paths. If signature verification runs before the capture middleware, set the result on the request using capture.signature_attribute (default: stripe_signature_verified). Captured records include request metadata, response data, exceptions, and processing duration. If the capture middleware does not find a boolean verification result, including when the attribute is missing or contains a non-boolean value, it records the webhook and writes a warning to the application log so the integration can be checked.

Exception messages and traces are omitted when redaction is disabled. Known configured sensitive values and common Stripe secret formats are omitted when redaction is enabled.

The default retention period is 30 days. Prune old records with:

php artisan stripe-watcher:prune
php artisan stripe-watcher:prune --days=7

Configure the default with retention.days.

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Thank you for considering contributing to Stripe Watcher! Please review our contributing guide to get started.

ivalin-venkov / stripe-watcher

Package info

Security

Fund package maintenance!

Statistics