README

Winglet-specific optional webhook extension package.

This package is intentionally coupled to winglet/core. It is not a generic webhook library for other frameworks.

Scope of this version

This first package version implements outbound webhook delivery only:

• domain event to webhook envelope mapping
• outbox persistence with Doctrine entities
• subscription matching
• delivery and delivery attempt persistence
• HMAC SHA-256 signing
• HTTP POST delivery
• retry scheduling
• CLI command: webhooks:dispatch

Inbound webhook receiving is intentionally not implemented in this first extraction.

Installation

composer require winglet/webhooks

Enable the extension in application or instance config:

return [
    'app' => [
        'extensions' => [
            \Winglet\Webhooks\Bridge\WebhookExtension::class,
        ],
    ],
    'webhooks' => [
        'enabled' => true,
        'outbound' => [
            'enabled' => true,
            'service_name' => 'my-service',
        ],
    ],
];

When the extension is loaded, it registers its services, CLI command and Doctrine mapping path through Winglet\Core\Extension\WingletExtensionInterface.

Publishing events

Applications publish domain events through the core-level interface:

use Winglet\Core\Integration\Events\EventPublisherInterface;

final class ExampleService
{
    public function __construct(private EventPublisherInterface $events) {}

    public function run(): void
    {
        $this->events->publish(new ExampleDomainEvent(...));
    }
}

If winglet/webhooks is enabled, the event is written to the webhook outbox. If the package is not enabled, core provides a no-op publisher.

Dispatching deliveries

winglet webhooks:dispatch 100 100

Run this from cron or a process supervisor, usually once per minute.

Database

Use resources/migrations/001_outbound_webhooks.sql as the initial schema for the package.

Tables:

• domain_event_outbox
• webhook_subscription
• webhook_delivery
• webhook_delivery_attempt

Standard headers

Outbound webhook requests use:

• X-Winglet-Event-Id
• X-Winglet-Event-Type
• X-Winglet-Timestamp
• X-Winglet-Source-Service
• X-Winglet-Signature

Signature format:

sha256=<hex-hmac>

Signing input:

timestamp + "\n" + rawBody