mohamedhekal/hookrelay

Reliable webhook delivery for Laravel: HMAC signing, retries, dead-letter queues, and replay

v0.1.0 2026-07-16 14:23 UTC

Requires

• php: ^8.2
• illuminate/console: ^11.0|^12.0
• illuminate/database: ^11.0|^12.0
• illuminate/events: ^11.0|^12.0
• illuminate/http: ^11.0|^12.0
• illuminate/queue: ^11.0|^12.0
• illuminate/routing: ^11.0|^12.0
• illuminate/support: ^11.0|^12.0

Requires (Dev)

• laravel/pint: ^1.18
• orchestra/testbench: ^9.0|^10.0
• pestphp/pest: ^3.0
• pestphp/pest-plugin-laravel: ^3.0
• phpstan/phpstan: ^2.0

MIT

• Mohamed Hekal

• php
• signature
• laravel
• saas
• webhook
• hmac
• webhooks
• laravel-package
• retries
• dead-letter
• outbound-webhooks

Published on Packagist.org on 2026-07-16 14:34 UTC

README

Search terms: laravel, webhooks, retries, hmac, dead-letter, saas, php, laravel-package, webhook, outbound-webhooks, signature.

Reliable webhook delivery for Laravel SaaS apps: fan-out events to subscriber endpoints with HMAC signatures, retries, dead-lettering, and replay—plus optional inbound ingest.

Problem

Webhook handlers fail silently, retries are ad hoc, and there is no audit trail or safe replay when a partner endpoint was down.

Installation

composer require mohamedhekal/hookrelay
php artisan vendor:publish --tag=hookrelay-config
php artisan migrate

Outbound quick start

use Hekal\HookRelay\Models\WebhookEndpoint;
use Hekal\HookRelay\Facades\HookRelay;

WebhookEndpoint::create([
    'name' => 'Merchant A',
    'url' => 'https://merchant.example/webhooks',
    'secret' => 'whsec_...',
    'events' => ['order.created', 'order.updated'],
]);

HookRelay::dispatch('order.created', [
    'id' => 1001,
    'total' => 2500,
], idempotencyKey: 'order:1001:created');

Receivers verify:

X-HookRelay-Signature: t=<unix>,v1=<hmac-sha256(secret, "timestamp.body")>
X-HookRelay-Event: order.created
X-HookRelay-Delivery: <uuid>

Inbound ingest

POST /hookrelay/ingest/{source}
X-HookRelay-Signature: t=...,v1=...
Idempotency-Key: optional

Configure secrets in hookrelay.inbound.sources. Listen for InboundWebhookReceived.

Commands

php artisan hookrelay:replay {id|uuid}
php artisan hookrelay:process-due

Features (v0.1)

• Endpoint subscriptions with event filters
• Signed outbound deliveries
• Attempt history
• Exponential backoff retries
• Dead-letter status after max attempts
• Idempotency keys per endpoint
• Inbound HMAC verification + event
• Replay / process-due Artisan commands

Testing

composer install && composer test

Architecture

See docs/architecture.md.

License

MIT