Weave Code
Laravel Github Webhooks Laravel Package
spatie/laravel-github-webhooks
Handle GitHub webhooks in Laravel. The package verifies GitHub signatures on incoming requests, logs valid calls to the database, and lets you dispatch jobs or events when specific webhooks hit your app.
spatie/laravel-github-webhooks is a Laravel package for receiving and handling GitHub webhooks securely. It automatically verifies GitHub signatures on incoming requests, stores every valid call in the database, and lets you dispatch jobs or events when specific webhook types arrive.
- Signature verification out of the box
- Database logging via
GitHubWebhookCall - Dispatch jobs/events for specific webhooks
- Easy payload access with
$webhookCall->payload() - Seamless Laravel queue integration
Frequently asked questions about Laravel Github Webhooks
- How do I install spatie/laravel-github-webhooks in Laravel?
- Run composer require spatie/laravel-github-webhooks, publish the config and migration, then run php artisan migrate. Register the package route macro, typically Route::githubWebhooks() in routes/api.php, set GITHUB_WEBHOOK_SECRET, and map your jobs in the config. You also need a running queue worker because accepted deliveries are processed asynchronously.
- Which Laravel and PHP versions does spatie/laravel-github-webhooks support?
- The package follows Spatie package conventions and is built on spatie/laravel-webhook-client and spatie/laravel-package-tools, so its constraints track those dependencies. Check the composer.json and Packagist metadata for the exact Laravel and PHP ranges of the release you plan to use. Treat the repository release dates as unverified and confirm the latest tag directly against Packagist before committing to an upgrade path.
- How does spatie/laravel-github-webhooks verify GitHub webhook signatures?
- A package-provided controller verifies the GitHub HMAC signature before accepting a delivery, using the signing_secret value from config, usually sourced from GITHUB_WEBHOOK_SECRET. The verification mechanics come from spatie/laravel-webhook-client. Make sure the verify_signature environment toggle is pinned to true in production, because a misconfigured env var can silently disable verification.
- How do I map GitHub webhook events to jobs or events in Laravel?
- In the package config you map event names such as issues.opened to your own job class, and a wildcard entry can catch all events. The package stores the call, dispatches ProcessGitHubWebhookJob, and that job fans out to your mapped job. You can also listen for github-webhooks::<event> events if you prefer listener-based handling, and your job receives a GitHubWebhookCall model whose payload() method returns the raw data.
- Does spatie/laravel-github-webhooks store webhook payloads in the database?
- Yes. After signature verification, every valid call is persisted to the github_webhook_calls table before any business logic runs, giving you an audit trail and a replay primitive. Raw payloads can contain user logins, emails, and issue or pull request content, so treat retention as a compliance surface. Default pruning is 10 days but is opt-in via a scheduled model:prune command, which is easy to forget.
- How do I test GitHub webhooks locally with spatie/laravel-github-webhooks?
- Expose your local application through a tunnel such as ngrok or Expose, configure the GitHub webhook to point at your Route::githubWebhooks() endpoint, and use a secret that matches your config. For automated tests, post payloads with a valid HMAC signature or model your tests on the package's own suite. Keeping the route in api.php avoids session and CSRF concerns; if you must use web.php, add the endpoint to VerifyCsrfToken except.
- Can I replay a GitHub webhook delivery in Laravel?
- Yes. Because accepted deliveries are stored as GitHubWebhookCall records, you can dispatch(new ProcessGitHubWebhookJob($call)) to re-run the fan-out for a stored call. The package does not dedupe on X-GitHub-Delivery, so both manual replays and GitHub redeliveries require idempotent jobs or an added uniqueness guard. Design for at-least-once semantics rather than assuming exactly-once processing.
- How do I handle multiple GitHub webhook secrets for different repositories?
- The config exposes a single signing_secret, so one endpoint effectively serves one secret. If you need to receive webhooks from multiple repositories or organizations with distinct secrets, use separate endpoints with distinct config, or implement a custom profile or model that resolves the correct secret from the payload's repository before verification. This single-secret design is the most likely architectural blocker at organization scale.
- Is spatie/laravel-github-webhooks production ready and maintained?
- It is a Spatie package with tests, a changelog, and tagged releases, but its adoption signal is weak at roughly 93 stars and no reported dependents, so it is not battle-tested by the masses. Architecturally it is a thin configuration surface over spatie/laravel-webhook-client, meaning dependency-chain risk matters more than this repository's code. Before production, pin verify_signature to true, add idempotency, define payload retention, and confirm the current release against Packagist.
- What are alternatives to spatie/laravel-github-webhooks?
- You can use spatie/laravel-webhook-client directly for generic webhook ingestion and add GitHub-specific signature and event mapping yourself. A custom controller that verifies the GitHub HMAC signature and dispatches your own queued jobs is also viable if you do not need the package's database logging and replay model. Choose based on whether you want built-in persistence, audit trails, and event-to-job mapping or prefer a smaller hand-rolled surface.
Weaver
How can I help you explore Laravel packages today?