PHPackages                             balescoses/github-webhooks - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. balescoses/github-webhooks

ActiveLibrary[API Development](/categories/api)

balescoses/github-webhooks
==========================

Laravel package for handling GitHub webhooks

10PHP

Since Aug 12Pushed 9mo agoCompare

[ Source](https://github.com/balesco/github-webhooks)[ Packagist](https://packagist.org/packages/balescoses/github-webhooks)[ RSS](/packages/balescoses-github-webhooks/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependenciesVersions (1)Used By (0)

Laravel GitHub Webhooks Package
===============================

[](#laravel-github-webhooks-package)

A comprehensive Laravel package for handling GitHub webhooks with database storage, signature validation, event management, and automated deployment capabilities.

Requirements
------------

[](#requirements)

- PHP ^8.2
- Laravel ^11.0 or ^12.0

Installation
------------

[](#installation)

1. Add the package to your local `composer.json`:

```
{
    "repositories": [
        {
            "type": "path",
            "url": "./packages/github-webhooks"
        }
    ],
    "require": {
        "laravel/github-webhooks": "*"
    }
}
```

2. Install the package:

```
composer require laravel/github-webhooks
```

3. Publish configuration and migrations:

```
php artisan vendor:publish --tag=github-webhooks-config
php artisan vendor:publish --tag=github-webhooks-migrations
```

4. Run migrations:

```
php artisan migrate
```

Configuration
-------------

[](#configuration)

### Environment Variables

[](#environment-variables)

Add these variables to your `.env` file:

```
# Secret for validating GitHub webhooks (optional but recommended)
GITHUB_WEBHOOK_SECRET=your-webhook-secret

# Route prefix (default: webhooks)
GITHUB_WEBHOOK_ROUTE_PREFIX=webhooks

# Store webhooks in database (default: true)
GITHUB_WEBHOOK_STORE=true

# Deployment Configuration
GITHUB_WEBHOOK_BRANCH=main
GITHUB_WEBHOOK_REPOSITORY_PATH=/path/to/your/project
GITHUB_WEBHOOK_RUN_COMPOSER=true
GITHUB_WEBHOOK_RUN_MIGRATIONS=true
GITHUB_WEBHOOK_RUN_NPM=false
GITHUB_WEBHOOK_RUN_CACHE_CLEAR=true
GITHUB_WEBHOOK_OPTIMIZE=true
GITHUB_WEBHOOK_CREATE_STORAGE_LINK=true
GITHUB_WEBHOOK_RESTART_QUEUE=false
```

### Configuration File

[](#configuration-file)

The package configuration file (`config/github-webhooks.php`) provides extensive options:

```
return [
    // GitHub webhook secret for signature validation
    'secret' => env('GITHUB_WEBHOOK_SECRET'),

    // Route configuration
    'route_prefix' => env('GITHUB_WEBHOOK_ROUTE_PREFIX', 'webhooks'),
    'middleware' => [
        // Add middleware like 'throttle:60,1'
    ],

    // Storage configuration
    'store_webhooks' => env('GITHUB_WEBHOOK_STORE', true),

    // Handler configuration
    'handlers' => [
        'push' => [
            App\Webhooks\Handlers\PushHandler::class,
        ],
        'pull_request' => [
            App\Webhooks\Handlers\PullRequestHandler::class,
        ],
        '*' => [
            App\Webhooks\Handlers\LogAllEventsHandler::class,
        ],
    ],

    // Error handling
    'continue_on_handler_failure' => true,

    // Auto-deployment configuration
    'auto_update_branches' => ['main', 'master', 'develop'],
    'branch' => env('GITHUB_WEBHOOK_BRANCH', 'main'),
    'repository_path' => env('GITHUB_WEBHOOK_REPOSITORY_PATH', base_path()),

    'deployment' => [
        'run_composer' => env('GITHUB_WEBHOOK_RUN_COMPOSER', true),
        'run_migrations' => env('GITHUB_WEBHOOK_RUN_MIGRATIONS', true),
        'run_npm' => env('GITHUB_WEBHOOK_RUN_NPM', false),
        'cache_clear' => env('GITHUB_WEBHOOK_RUN_CACHE_CLEAR', true),
        'optimize' => env('GITHUB_WEBHOOK_OPTIMIZE', true),
        'create_storage_link' => env('GITHUB_WEBHOOK_CREATE_STORAGE_LINK', true),
        'restart_queue' => env('GITHUB_WEBHOOK_RESTART_QUEUE', false),
    ]
];
```

### GitHub Configuration

[](#github-configuration)

1. Go to your GitHub repository settings
2. Click "Webhooks" in the left menu
3. Click "Add webhook"
4. Configure:
    - **Payload URL**: `https://your-domain.com/webhooks/github`
    - **Content type**: `application/json`
    - **Secret**: Your secret (same as `GITHUB_WEBHOOK_SECRET`)
    - **Events**: Select the events you want to receive

Features
--------

[](#features)

### ✅ Core Features

[](#-core-features)

- **Webhook Reception**: Secure endpoint for GitHub webhooks
- **Signature Validation**: HMAC-SHA256 signature verification
- **Database Storage**: Store webhook data for audit and replay
- **Event Handling**: Flexible handler system for different events
- **Error Handling**: Robust error handling with optional failure tolerance

### ✅ Deployment Automation

[](#-deployment-automation)

- **Automated Git Pull**: Automatic repository updates on push events
- **Composer Management**: Automatic dependency installation
- **NPM Support**: Node.js dependency and build management
- **Database Migrations**: Automatic migration execution
- **Cache Management**: Cache clearing and optimization
- **Queue Management**: Worker restart capability
- **Storage Links**: Automatic symbolic link creation

### ✅ Management Commands

[](#-management-commands)

- **Webhook Management**: List, filter, and reprocess webhooks
- **Repository Operations**: Clone and update repositories
- **Secret Generation**: Secure webhook secret generation
- **Configuration Validation**: Validate webhook setup

Usage
-----

[](#usage)

### Custom Handlers

[](#custom-handlers)

Create handlers to process GitHub events:

```