Download the PHP package techrays-labs/laravel-webhooker without Composer

Laravel Webhooker

A Laravel-native Webhook Reliability Engine for outbound and inbound webhook management with intelligent retry, replay, circuit breaker, and a built-in dashboard.

The Problem

Webhooks are critical infrastructure, but building reliable webhook delivery is hard. You need retry logic, signature verification, attempt logging, failure recovery, and operational visibility. Most teams either build fragile one-off solutions or rely on external SaaS services.

Laravel Webhooker gives you production-grade webhook infrastructure as a Composer package. Zero external dependencies. No SaaS billing. Just install, configure, and ship.

Features

Core

• Outbound Delivery - Queue-based async delivery with configurable timeout
• Inbound Handling - Receive, verify, deduplicate, and process inbound webhooks
• Exponential Backoff Retry - Configurable max attempts, delay, and multiplier
• HMAC Signatures - Automatic signing for outbound, verification for inbound
• Attempt Logging - Full record of every delivery attempt with status, duration, and errors
• Replay - Re-dispatch any failed event via Artisan command or dashboard
• Pruning - Automatic retention management to prevent unbounded storage growth

Observability

• Webhook Metrics - Aggregated stats (success rate, response time, failure rate) via a WebhookMetrics service
• Endpoint Health Status - Computed health classification (healthy, degraded, failing, unknown) per endpoint
• Laravel Events - Native event dispatching at key lifecycle points for custom listeners
• Structured Logging - Optional dedicated log channel with structured context

Control

• Circuit Breaker - Auto-disable failing endpoints, cooldown period, half-open recovery
• Endpoint Tagging - Tag/group endpoints, dispatch to all endpoints by tag
• Enable/Disable API - Programmatically toggle endpoints with reason tracking
• Per-Endpoint Retry - Override global retry settings per endpoint

Developer UX

• Testing Facade - Webhook::fake() with assertion helpers for your test suite
• Inbound Simulator - Artisan command to simulate inbound webhook deliveries locally
• Debug Mode - Verbose logging of full request/response cycles in development
• Tinker Helpers - inspect(), lastFailed(), retryLast(), stats() on the facade

Hardening

• Rate Limiting - Per-endpoint outbound rate limits using Laravel's RateLimiter
• Payload Validation - Schema-based validation of outbound payloads before dispatch
• IP Allowlist - Restrict inbound webhooks to known IP addresses (supports CIDR)
• Secret Rotation - Rotate endpoint secrets with a configurable grace period
• Idempotency Keys - Prevent duplicate outbound deliveries

Scaling & Reliability (v2.0)

• Storage Driver Abstraction - Pluggable storage backends via Laravel's Manager pattern
• Dead-Letter Queue - Auto-capture events that exhaust all retries for inspection and manual retry
• Event Batching - Dispatch to multiple endpoints as a tracked batch with progress monitoring
• Endpoint Health History - Periodic health snapshots for trend analysis over time
• Multi-Database Support - Read/write connection separation for read replicas
• Table Partitioning - MySQL (RANGE) and PostgreSQL (declarative) partitioning for high-volume tables
• Horizontal Scaling - Distributed locking for safe multi-worker webhook processing

Dashboard

• Stats Overview - 24h event counts, success rate, average response time, endpoint health breakdown
• Event Timeline - Visual timeline of delivery attempts with status codes, durations, and errors
• Bulk Actions - Select and replay or delete multiple events at once
• Endpoint Detail Page - Config, health, circuit breaker state, 7-day sparkline
• Tag Filtering - Filter events by endpoint tag
• Dark Mode - CSS variable theming with prefers-color-scheme and manual toggle
• Analytics Dashboard - Comprehensive analytics with success rates, response times, and trends

REST API (v1.0.0)

• Full CRUD for Endpoints - Create, read, update, delete endpoints via API
• Event Management - List, view, replay, retry, delete events
• Analytics Endpoints - Programmatic access to delivery statistics
• Token-based Authentication - Secure API tokens with abilities and expiration
• Schema Validation - Validate event payloads against registered schemas

Event Transforms (v1.0.0)

• Per-Endpoint Transforms - Modify payloads before delivery to specific endpoints
• Include/Exclude Fields - Filter payload fields with simple configuration
• Rename Fields - Remap field names for different consumers
• Add Computed Fields - Inject dynamic values into payloads
• Custom Transformers - Implement WebhookTransformer interface for complex transformations

Event Filtering (v1.0.0)

• Pattern-based Subscriptions - Subscribe endpoints to specific event patterns using wildcards
• Wildcard Matching - Support * and ? wildcards (e.g., order.*, user.created)
• Multiple Patterns - Multiple filter patterns per endpoint

Event Schema Registry (v1.0.0)

• Schema Definitions - Define JSON schemas for webhook event types
• Validation - Validate inbound/outbound payloads against registered schemas
• Schema API - RESTful management of event schemas

Real-time WebSockets (v1.0.0)

• Live Delivery Updates - Broadcast delivery status changes in real-time
• Channel-based Events - Subscribe to all deliveries or endpoint-specific channels
• Laravel Reverb/Pusher - Works with any Laravel broadcast driver

Plugin System (v1.0.0)

• Extensible Architecture - Register custom plugins to modify webhook behavior
• Payload Transformation - Plugins can modify payloads before sending
• Event Hooks - Hook into webhook lifecycle events (sending, delivered, failed)
• Event Filtering - Plugins can filter which events reach endpoints
• Priority-based Execution - Plugins execute in priority order

Requirements

• PHP 8.1+
• Laravel 10, 11, 12, or 13

Installation

Publish the configuration file:

Run the migrations:

Quick Start: Outbound Webhooks

Register an endpoint

Dispatch an event

Dispatch with idempotency key

Broadcast to all active outbound endpoints

Dispatch to tagged endpoints

The event is persisted immediately and delivered asynchronously via your queue. If delivery fails, it retries automatically with exponential backoff.

Quick Start: Inbound Webhooks

Register an inbound endpoint

Inbound webhooks are received at:

Each endpoint gets a unique route_token (e.g., ep_a8f3kx9m2b7q) auto-generated on creation. The full URL is displayed in the dashboard for easy copy-paste.

The package automatically:

1. Checks IP allowlist (if enabled)
2. Verifies the HMAC signature via the X-Webhook-Signature header
3. Rejects invalid or missing signatures with 401
4. Deduplicates events via the X-Webhook-Event-ID header
5. Persists the payload
6. Queues it for async processing

Custom inbound processing

Bind your own processor in a service provider:

Dashboard

The built-in dashboard provides operational visibility into your webhook events.

Access it at /webhooks (configurable prefix).

The dashboard includes:

• Stats overview - Total events, delivered, failed, pending, success rate, avg response time, endpoint health breakdown, active circuit breakers
• Event list - Filterable by status, endpoint, event name, and tag with bulk actions (replay, delete)
• Event detail - Payload preview, delivery timeline with color-coded status, expandable response bodies, replay button
• Endpoint list - Route tokens, URLs, direction, active/disabled status, tags, inbound URLs
• Endpoint detail - Configuration, health status, circuit breaker state, 7-day success rate sparkline, recent events
• Dark mode - Toggle via button, respects system preference, persists via cookie

Authorization

The dashboard is protected by a Laravel Gate. Define it in your AuthServiceProvider:

Disable the dashboard

Circuit Breaker

The circuit breaker prevents wasting queue resources on consistently failing endpoints.

States:

• CLOSED - Endpoint is healthy, deliveries proceed normally
• OPEN - Endpoint has failed too many times, deliveries are paused
• HALF_OPEN - After cooldown, allows a test delivery to check recovery

The circuit breaker can be bypassed with --force on the replay command.

Endpoint Management

Enable/Disable

Tagging

Secret Rotation

After rotation, both old and new secrets are accepted during a configurable grace period (default: 24 hours). Expired previous secrets are cleaned up by the webhook:secret:cleanup command.

Retention & Pruning

By default, webhook events are retained for 30 days. Run the prune command regularly:

Or with a custom retention period:

Schedule it in your application:

Retry Configuration

The default retry strategy uses exponential backoff:

This produces delays of: 10s, 20s, 40s, 80s, 160s.

Per-endpoint retry

Custom retry strategy

Implement the RetryStrategy contract and bind it in your service provider:

Rate Limiting

Prevent overwhelming destination servers:

Per-endpoint override via the rate_limit_per_minute column on webhook_endpoints.

Payload Validation

Validate outbound payloads before dispatch:

Invalid payloads throw InvalidWebhookPayloadException.

IP Allowlist (Inbound)

Restrict inbound webhooks to known IPs:

Per-endpoint allowlists can be set via the allowed_ips JSON column.

Storage Driver Abstraction

Laravel Webhooker uses a pluggable storage layer based on Laravel's Manager pattern. The default driver is eloquent.

Custom storage drivers

Extend the WebhookStorageManager to register your own drivers:

Dead-Letter Queue

Events that exhaust all retries can be automatically moved to a dead-letter queue for inspection and manual retry.

Managing the DLQ

The WebhookMovedToDeadLetter event is fired when an event enters the DLQ.

Event Batching

Dispatch the same event to multiple endpoints as a tracked batch:

Endpoint Health History

Capture periodic health snapshots for trend analysis:

Schedule the snapshot command:

Access health history programmatically:

Multi-Database Support

Route reads to a replica and writes to the primary database:

All repository queries are automatically routed to the correct connection.

Table Partitioning

For high-volume installations, partition the webhook_events and webhook_attempts tables:

Publish the partition migration stubs:

Manage partitions via Artisan:

Supports MySQL (RANGE partitioning) and PostgreSQL (declarative partitioning).

Horizontal Scaling

For multi-worker deployments, enable distributed locking to prevent duplicate event processing:

When enabled, each webhook job acquires a distributed lock before processing. This ensures that even with multiple queue workers, each event is processed exactly once.

You can provide your own lock implementation by binding the WebhookLock contract:

Testing

Use the testing facade in your application's test suite:

Or use the trait:

Debug Mode

Enable verbose logging in development:

A runtime warning is logged if debug mode is enabled in a production environment.

Laravel Events

The package fires native Laravel events at key lifecycle points:

CLI Commands

Configuration Reference

Upgrade Guide

Upgrading from v0.1.0 to v2.0.0

v2.0.0 introduces breaking changes to the WebhookRepository contract, DispatchWebhookJob, and ProcessInboundWebhookJob. If you have custom implementations of these contracts, you will need to update them.

1. Run the new migrations:

2. If you have a custom WebhookRepository implementation, add the new method signatures from the contract.

3. If you dispatch jobs manually (outside the facade), update handle() calls to include the WebhookLock parameter.

4. Review the new config sections added to config/webhooks.php and publish updated config if needed:

Roadmap

v0.1.0 (Released)

Core webhook engine: outbound/inbound delivery, retry, signatures, circuit breaker, dashboard, tagging, rate limiting, payload validation, IP allowlist, secret rotation, idempotency, testing facade, debug mode.

v2.0.0 (Released)

• Storage driver abstraction
• Dead-letter queue
• Event batching
• Endpoint health history
• Multi-database support
• Table partitioning support
• Horizontal scaling support

Future

• Webhook event transforms (modify payload per endpoint)
• Webhook event filtering (subscribe endpoints to specific event patterns)
• GraphQL / REST API for programmatic management
• Webhook delivery analytics dashboard
• Webhook event schema registry
• Real-time delivery monitoring via WebSockets
• Plugin system for third-party integrations

Contributing

Contributions are welcome. Please follow these guidelines:

1. Fork the repository
2. Create a feature branch (feature/your-feature)
3. Write tests for your changes
4. Ensure all tests pass (vendor/bin/phpunit)
5. Format code with Laravel Pint (vendor/bin/pint)
6. Use conventional commits (feat:, fix:, refactor:, test:, docs:)
7. Submit a pull request

License

MIT License. See LICENSE for details.