Github Webhook Bundle Laravel Package

Getting Started

• Install via Composer: composer require kurozumi/github-webhook-bundle
• Publish the config file: php artisan vendor:publish --provider="Kurozumi\GitHubWebhookBundle\GitHubWebhookServiceProvider" --tag="config"
• Add GITHUB_WEBHOOK_SECRET=your_secret to your .env file (use the same secret you configure in GitHub)
• The package registers a webhook endpoint at /github/webhook by default. Point your GitHub repository/organisation webhook to https://yourdomain.com/github/webhook (or your custom route) and provide the secret.
• First use case: listen for a push event by creating a listener for Kurozumi\GitHubWebhookBundle\Events\GitHubWebhookReceived and checking $event->payload['ref'] or the event type.

Implementation Patterns

• The package verifies the X-Hub-Signature-256 header automatically. Use the provided GitHubWebhook facade to parse and validate payloads if you need custom handling.
• It dispatches specific events for common GitHub webhook types (e.g. PushEvent, PullRequestEvent) in addition to the generic GitHubWebhookReceived event. Register listeners in EventServiceProvider for the events you care about.
• For quick prototyping, listen to the generic event and switch on $event->payload['action'] or the X-GitHub-Event header stored in $event->eventType.
• Use middleware to restrict the webhook route by IP (GitHub’s hook IPs) or to add additional security layers.
• In tests, use Http::fake() or the package’s testing helpers to simulate a valid webhook request without hitting GitHub.
• To customise the route path or middleware, edit config/github-webhook.php after publishing.

Gotchas and Tips

• The secret must match exactly between GitHub and your .env; a mismatch causes a 403 response. Double‑check for trailing spaces or newlines.
• Not all GitHub event types are mapped to dedicated event classes. For unsupported events, rely on the generic GitHubWebhookReceived event and inspect $event->payload.
• GitHub truncates payloads larger than 25 MB; handle large payloads gracefully if you expect big pushes.
• Use php artisan route:list to confirm the webhook route is registered and not conflicting with existing routes.
• For debugging, log the raw request or enable Laravel’s debug logging – the package does not log by default.
• Extension points: you can override the controller, middleware, or event listeners by binding your own implementations in a service provider. Check the package’s config file for available options.