Weave Code
Laravel Github Webhooks Laravel Package
spatie/laravel-github-webhooks
Handle GitHub webhooks in Laravel: verify signatures, log valid calls, and dispatch jobs/events per webhook type. Includes a GitHubWebhookCall model to access payloads and queueable handlers for event-driven integrations.
Handle GitHub webhooks in a Laravel application
Frequently asked questions about Laravel Github Webhooks
- How do I install and set up spatie/laravel-github-webhooks in Laravel?
- Run `composer require spatie/laravel-github-webhooks`, publish the config and migrations with `php artisan vendor:publish --tag=github-webhooks-config,migrations`, then add the route macro in `routes/api.php` using `Route::githubWebhooks('webhook-endpoint')`. Run the migrations afterward.
- Does this package support Laravel 10 and PHP 8.1+?
- Yes, the package is fully compatible with Laravel 10 and PHP 8.1+. It aligns with Laravel’s latest features like typed properties and modern queue systems. Check the [GitHub repo](https://github.com/spatie/laravel-github-webhooks) for version-specific updates.
- How does signature verification work, and can I customize it?
- The package automatically verifies GitHub’s HMAC signature for every incoming webhook request. You can customize the secret key in the config file (`github_webhooks_secret`). If you need additional validation (e.g., IP whitelisting), extend the `VerifyGitHubWebhookSignature` middleware.
- Can I process webhook payloads asynchronously with queues?
- Absolutely. The package dispatches queued jobs (via `ShouldQueue`) for each webhook event. Create a job class (e.g., `HandleIssueOpenedWebhookJob`) and map it to the event in the config. This ensures high-performance handling even for high-volume webhooks.
- How do I access the raw payload data in my job handler?
- Inject the `GitHubWebhookCall` model into your job’s constructor, then use the `payload()` method to retrieve the raw JSON payload. For example: `$this->webhookCall->payload()`. You can also access parsed data via `$this->webhookCall->payload['action']` or similar keys.
- What happens if a webhook fails to process? Can I retry failed jobs?
- Failed jobs will be retried based on Laravel’s queue retry logic. To handle persistent failures, implement custom retry logic in your job or use Laravel’s `failed` event to log errors. For critical workflows, consider integrating with Laravel Horizon or a dead-letter queue.
- Is there a way to filter or ignore specific webhook events?
- Yes, use the `ProcessEverythingWebhookProfile` or create a custom profile to filter events. In your job, check the payload for specific conditions (e.g., `$this->webhookCall->payload['action'] === 'opened'`) and exit early if the event doesn’t match your criteria.
- How do I test webhook handlers locally without GitHub’s real webhooks?
- Use tools like [ngrok](https://ngrok.com/) to expose your local server to GitHub, then configure a test webhook in your GitHub repo. Alternatively, mock the `GitHubWebhookCall` model in your tests or use GitHub’s [webhook testing tool](https://docs.github.com/en/developers/webhooks-and-events/webhooks/testing-webhooks).
- What are the database requirements for storing webhook calls?
- The package uses Eloquent to store webhook calls in a `github_webhook_calls` table. It supports MySQL, PostgreSQL, and SQLite. The default retention is 10 days, but you can adjust `prune_webhook_calls_after_days` in the config. For large-scale apps, consider archiving old logs to a separate storage system.
- Are there alternatives to this package for handling GitHub webhooks in Laravel?
- Alternatives include `laravel-github` (for broader GitHub API integration) or custom solutions using Laravel’s HTTP middleware and queues. However, `spatie/laravel-github-webhooks` stands out for its built-in signature verification, logging, and seamless job/event integration, reducing boilerplate significantly.
Weaver
How can I help you explore Laravel packages today?