Weave Code
Laravel Github Webhooks Laravel Package
spatie/laravel-github-webhooks
Handle GitHub webhooks in Laravel with signature verification, automatic logging to the database, and easy job/event dispatching per webhook type. Configure handlers, queue processing, and access the webhook payload via a stored call model.
Handle GitHub webhooks in a Laravel application
Frequently asked questions about Laravel Github Webhooks
- How do I set up GitHub webhooks in Laravel to handle push events asynchronously?
- Install the package via Composer, publish the config with `php artisan vendor:publish`, and define a job like `HandlePushWebhookJob` that implements `ShouldQueue`. The package automatically validates GitHub’s HMAC signature and logs calls to the database. Use `@queue` on your job to process pushes asynchronously via Laravel’s queue system.
- Which Laravel versions does `spatie/laravel-github-webhooks` support?
- The package supports Laravel 9.x and 10.x. Check the [GitHub repository](https://github.com/spatie/laravel-github-webhooks) for the latest compatibility details. Always ensure your Laravel version aligns with the package’s requirements to avoid integration issues.
- Can I customize payload validation for GitHub webhooks beyond GitHub’s schema?
- Yes, override the `shouldProcess()` method in your job class to add custom validation logic. For example, reject webhooks with specific payload attributes or enforce business rules before processing. This ensures only valid payloads trigger your application logic.
- What’s the best way to test GitHub webhook endpoints locally without hitting GitHub’s API?
- Use the `GitHubWebhooks::fake()` helper in your tests to simulate webhook payloads. This allows you to assert whether jobs were dispatched or verify payload data without making real HTTP requests. The package includes testing utilities to mock GitHub events seamlessly.
- How do I handle duplicate webhook events (e.g., retries from GitHub)?
- GitHub webhooks are idempotent by design, but you can add deduplication logic in your job’s `handle()` method. Check the `GitHubWebhookCall` model’s `payload()` for unique identifiers (e.g., `pull_request.id`) and skip processing if the event was already handled. Combine this with Laravel’s queue retries for failed jobs.
- Should I use Redis or database queues for handling GitHub webhooks at scale?
- Redis is recommended for high-throughput scenarios due to its lower latency and better performance under load. Database queues work for smaller applications but may struggle with spikes. Monitor queue backlogs and adjust based on your traffic—critical events (e.g., CI/CD triggers) should use synchronous processing if low latency is required.
- How do I secure the GitHub webhook secret in production?
- Store the secret in Laravel’s `.env` file (e.g., `GITHUB_WEBHOOK_SECRET`). Never hardcode it in your application. Rotate secrets periodically by updating both GitHub’s webhook configuration and your Laravel environment. Use Laravel’s `env()` helper to access the secret securely in your code.
- Are there alternatives to this package for handling GitHub webhooks in Laravel?
- Yes, alternatives include `laravel-github` (for broader GitHub API integration) or rolling your own solution with Laravel’s HTTP middleware and queues. However, `spatie/laravel-github-webhooks` stands out for its Laravel-native integration, built-in signature validation, and modular job-based approach, reducing boilerplate significantly.
- How can I monitor failed GitHub webhook deliveries or job processing errors?
- Leverage Laravel’s logging system (e.g., database or stack drivers) to track webhook calls and job failures. Integrate with tools like Sentry or Prometheus for real-time monitoring. The package logs all incoming webhook calls to the `github_webhook_calls` table, which you can query for debugging or analytics.
- What’s the performance impact of validating GitHub’s HMAC signature for every webhook?
- The signature validation adds minimal CPU overhead, typically under 1ms per request. For high-traffic applications, cache the secret in memory (e.g., using Laravel’s cache facade) or use signed middleware for critical paths. Benchmark your setup to ensure it meets your latency requirements.
Weaver
How can I help you explore Laravel packages today?