README

LaraWebhook is an open-source Laravel package for handling incoming webhooks in a secure, reliable, and simple way. Validate signatures, manage retries, log events, and integrate popular services (Stripe, GitHub, Slack, etc.) in minutes.

✨ Features

Signature Validation: Verify webhook authenticity (Stripe, GitHub, etc.)
Retry Management: Automatically retry failed webhooks with exponential backoff
Detailed Logging: Store events and errors for debugging
Interactive Dashboard: Modern UI with Alpine.js and Tailwind CSS for log management
REST API: Programmatic access to webhook logs with filtering and pagination
Replay Webhooks: Re-process failed webhooks from dashboard or API
Easy Integration: Minimal configuration, compatible with Laravel 9+
Extensible: Add your own validators or services

📦 Installation

Install the package via Composer:
```
composer require t-willm/larawebhook
```

Publish the configuration:

php artisan vendor:publish --provider="Twillm\LaraWebhook\LaraWebhookServiceProvider"

Configure your signature keys in config/larawebhook.php:

'stripe' => [
     'secret' => env('STRIPE_WEBHOOK_SECRET'),
     'tolerance' => 300, // Tolerance in seconds
],

🛠 Usage

Using the Middleware (Recommended)

The easiest way to validate webhooks is using the validate-webhook middleware:

// routes/web.php
Route::post('/stripe-webhook', function () {
    // Webhook is automatically validated and logged
    // Process your webhook here
    $payload = json_decode(request()->getContent(), true);

    // Handle the event
    event(new \App\Events\StripeWebhookReceived($payload));

    return response()->json(['status' => 'success']);
})->middleware('validate-webhook:stripe');

Route::post('/github-webhook', function () {
    // Webhook is automatically validated and logged
    $payload = json_decode(request()->getContent(), true);

    // Handle the event
    event(new \App\Events\GithubWebhookReceived($payload));

    return response()->json(['status' => 'success']);
})->middleware('validate-webhook:github');

What the middleware does:

✅ Validates the webhook signature
✅ Automatically logs the event to the database
✅ Returns 403 for invalid signatures
✅ Returns 400 for missing headers or malformed payloads

Manual Validation (Advanced)

For more control, you can manually validate webhooks:

// app/Http/Controllers/WebhookController.php
use Twillm\Larawebhook\Services\WebhookValidator;
use Illuminate\Http\Request;

public function handleWebhook(Request $request)
{
    $payload = $request->getContent();
    $signature = $request->header('Stripe-Signature');
    $secret = config('larawebhook.services.stripe.webhook_secret');

    $validator = new WebhookValidator($secret);

    try {
        // Validate and log in one call
        $log = $validator->validateAndLog(
            $payload,
            $signature,
            'stripe',
            'payment_intent.succeeded'
        );

        // Process the event
        event(new \App\Events\StripeWebhookReceived(json_decode($payload, true)));

        return response()->json(['status' => 'success']);
    } catch (\Exception $e) {
        return response($e->getMessage(), 403);
    }
}

🔧 Configuration

Modify config/larawebhook.php to:

Add services (Stripe, GitHub, etc.)
Configure validation tolerance
Enable/disable logging

Example:

'services' => [
    'stripe' => [
        'secret' => env('STRIPE_WEBHOOK_SECRET'),
        'tolerance' => 300,
    ],
    'github' => [
        'secret' => env('GITHUB_WEBHOOK_SECRET'),
        'tolerance' => 300,
    ],
],

📊 Logging

Webhooks are logged in the webhook_logs table with:

service (e.g., stripe, github)
event (e.g., payment_intent.succeeded)
status (success/failed)
payload (webhook content)
created_at

To view logs:

php artisan tinker
>>> \ThibaudWillm\LaraWebhook\Models\WebhookLog::latest()->get();

📊 Dashboard & API

LaraWebhook provides a modern dashboard built with Alpine.js and Tailwind CSS to visualize and manage webhook logs.

Access the Dashboard

The dashboard is automatically available at:

http://your-app.test/larawebhook/dashboard

Features:

📋 Paginated webhook logs table
🔍 Filter by service, status, and date
👁️ View detailed payload and error messages
🔄 Replay failed webhooks
📱 Fully responsive design

API Endpoints

The package also provides REST API endpoints for programmatic access:

Get Webhook Logs

GET /api/larawebhook/logs

Query Parameters:

service - Filter by service (stripe, github, etc.)
status - Filter by status (success, failed)
date - Filter by date (YYYY-MM-DD)
per_page - Results per page (default: 10)
page - Page number

Example:

curl "https://your-app.test/api/larawebhook/logs?service=stripe&status=failed&per_page=25"

Response:

{
  "data": [
    {
      "id": 1,
      "service": "stripe",
      "event": "payment_intent.succeeded",
      "status": "success",
      "payload": {...},
      "attempt": 0,
      "created_at": "01/01/2024 10:30:00"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 10,
    "total": 50
  },
  "links": {
    "first": "...",
    "last": "...",
    "prev": null,
    "next": "..."
  }
}

Replay a Webhook

POST /api/larawebhook/logs/{id}/replay

Example:

curl -X POST "https://your-app.test/api/larawebhook/logs/123/replay" \
  -H "Content-Type: application/json"

Response:

{
  "success": true,
  "message": "Webhook replayed successfully!",
  "log": {
    "id": 124,
    "service": "stripe",
    "event": "payment_intent.succeeded",
    "status": "success",
    "attempt": 1
  }
}

Dashboard Configuration

Customize the dashboard in config/larawebhook.php:

'dashboard' => [
    'enabled' => env('LARAWEBHOOK_DASHBOARD_ENABLED', true),
    'path' => env('LARAWEBHOOK_DASHBOARD_PATH', '/larawebhook/dashboard'),
    'middleware' => env('LARAWEBHOOK_DASHBOARD_MIDDLEWARE', 'web'),
],

Disable the dashboard:

LARAWEBHOOK_DASHBOARD_ENABLED=false

Change the dashboard path:

LARAWEBHOOK_DASHBOARD_PATH=/admin/webhooks

Add authentication middleware:

LARAWEBHOOK_DASHBOARD_MIDDLEWARE=web,auth

🧪 Tests

Run tests with:

composer test

(Tests cover validation, retries, and logging.)

🚀 Release Process

This project uses Release Please for automated releases and changelog management.

How it works

Commit with Conventional Commits format:

git commit -m "feat: add new webhook validation"
git commit -m "fix: resolve signature verification bug"
git commit -m "docs: update installation instructions"

Release Please creates a PR automatically when changes are pushed to master:
- Generates/updates CHANGELOG.md based on commits
- Bumps version in .release-please-manifest.json
- Creates a release PR titled "chore(master): release X.Y.Z"
Review and merge the release PR:
- Review the generated changelog
- Merge the PR to trigger the release
Automatic actions on merge:
- Creates a GitHub Release with tag vX.Y.Z
- Runs tests and static analysis
- Packagist syncs automatically (no manual webhook needed)

Conventional Commits format

feat: → New feature (bumps minor version)
fix: → Bug fix (bumps patch version)
docs: → Documentation changes
style: → Code style changes (formatting, etc.)
refactor: → Code refactoring
perf: → Performance improvements
test: → Adding/updating tests
chore: → Maintenance tasks
ci: → CI/CD changes

Breaking changes: Add ! after type or add BREAKING CHANGE: in commit body to bump major version.

Example:

git commit -m "feat!: change webhook validation API"

📱 Telegram Notifications

LaraWebhook supports Telegram notifications for GitHub Actions events:

❌ Test Failures: Get notified when tests fail on push or pull requests
🚀 New Releases: Announcement when a new version is published

Setup Instructions

Create a Telegram Bot:
- Chat with @BotFather on Telegram
- Send /newbot and follow instructions
- Save your bot token
Get Your Chat ID (NOT the bot's ID!):
- Easy method: Chat with @userinfobot to get YOUR Chat ID
- Alternative: Start a chat with YOUR bot, then visit https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates
- ⚠️ Important: Use YOUR personal Chat ID, not the bot's ID (bots can't message themselves!)
Add GitHub Secrets:
- Go to repository Settings → Secrets and variables → Actions
- Add two secrets:
  - TELEGRAM_BOT_TOKEN: Your bot token
  - TELEGRAM_CHAT_ID: Your chat ID
Verify: Push changes and watch for notifications!

For detailed setup instructions, see .github/TELEGRAM_SETUP.md

Example Notifications

Test Failure:

❌ Tests Failed

Repository: t-willm/larawebhook
Branch: feature/new-feature
Commit: abc123def
Author: username
Workflow: View Details

New Release:

🚀 New Release Published

Repository: t-willm/larawebhook
Version: v1.5.0
Release Notes: View on GitHub
Packagist: Install Now

🤝 Contributing

Fork the repository
Create a branch (git checkout -b feature/my-feature)
Commit your changes (git commit -am 'Add my feature')
Push the branch (git push origin feature/my-feature)
Open a Pull Request

(See CONTRIBUTING.md for more details.)

📄 License

This project is licensed under the MIT License. See LICENSE for more information.

t-willm / larawebhook

Maintainers

Details