- Which Laravel versions does this package support, and will it work with Laravel 12?
- The package is officially tested for Laravel 10.x and 11.x. While no Laravel 12-specific updates are confirmed, the core middleware and service container integration suggests compatibility with minor adjustments. Always check the `composer.json` constraints or fork if needed for newer versions.
- How do I install and configure the package for Mailgun webhooks?
- Run `composer require jeffersongoncalves/laravel-webhook-signatures`, then add your Mailgun secret key to `config/webhook_signatures.php` under the `mailgun` provider. Apply the middleware to your route: `Route::post('/mailgun-webhook', [WebhookController::class, 'handle'])->middleware('webhook.signature:mailgun');`. No additional setup is required for basic HMAC verification.
- Does this package support non-HMAC signature algorithms like RSA or ECDSA?
- The package is optimized for HMAC-SHA256, which covers Mailgun, SendGrid, and AWS SNS/SES. If you need RSA or ECDSA (e.g., for Stripe or custom providers), you’ll need to extend the `WebhookSignature` class or use a separate library like `webhook-signature-php` for algorithm-specific logic.
- How can I test webhook signature validation in Laravel’s HTTP tests?
- Use Laravel’s `actingAsWebhook()` helper or manually set the `X-Hub-Signature` header in your test payload. For example: `$response = $this->post('/webhook/mailgun', [], ['HTTP_X_HUB_SIGNATURE' => 'sha256=...']);`. The package will automatically validate the signature before reaching your controller logic.
- What happens if a webhook signature fails validation? Can I log or retry failed requests?
- Failed validations trigger a `401 Unauthorized` response by default. To log failures, inject the `WebhookSignature` service into your controller and call `validate()` with a custom callback: `$signature->validate($request, function() { Log::error('Webhook signature failed'); });`. For retries, use Laravel Queues to defer processing or implement a dead-letter queue for persistent failures.
- Is it safe to store webhook secrets in the Laravel config file, or should I use environment variables?
- While the config file works for development, **always use environment variables** (e.g., `.env`) for production secrets. The package respects Laravel’s `config('services')` caching, so secrets loaded from `.env` won’t appear in logs or environment dumps. Example: `WEBHOOK_MAILGUN_SECRET=your_key_here` in `.env`.
- Can I use this package with serverless Laravel (e.g., Bref or Vapor)?
- Yes, the middleware-based design is ideal for serverless. Deploy the package as a Lambda function or Vapor endpoint, and the signature verification will run before your business logic. Ensure your serverless environment has access to the `.env` secrets via AWS Secrets Manager or Vapor’s configuration.
- Are there performance concerns for high-volume webhooks (e.g., 10,000+ requests/minute)?
- HMAC verification adds negligible latency (~1–5ms per request). For extreme scale, offload validation to a queue worker (e.g., `dispatch(new VerifyWebhookJob($request))`) or use a dedicated microservice. Benchmark with your expected load, as cryptographic operations are CPU-bound.
- Does the package support rotating webhook secrets without downtime?
- Yes, update the secret in your `.env` file and restart Laravel’s queue workers or server. The package reads secrets dynamically from the config, so no code changes are needed. For zero-downtime deployments, use a feature flag to validate against both old and new secrets temporarily.
- What alternatives exist if this package doesn’t support my webhook provider?
- For unsupported providers, use the standalone `webhook-signature-php` library or extend this package by creating a custom provider class. Example: `php artisan make:provider CustomWebhookProvider`. The package’s modular design makes it easy to add new algorithms or header formats without forking.