README

Bridges yii3-outbox and yii3-webhooks for durable at-least-once webhook delivery. Each outbox message is converted to a WebhookEvent and dispatched to configured endpoints via an injected WebhookDispatcher.

Using an AI coding assistant? llms.txt has a compact API reference designed for LLMs.

Requirements

• PHP 8.3–8.5
• rasuvaeff/yii3-outbox ^1.0
• rasuvaeff/yii3-webhooks ^1.0
• A WebhookDispatcher implementation (e.g. a PSR-18-based adapter in your app)
• A WebhookDeliveryStorage implementation (e.g. yii3-webhooks-db)

Installation

composer require rasuvaeff/yii3-outbox-webhooks-bridge

Usage

1. Configure endpoints

use Rasuvaeff\Yii3OutboxWebhooksBridge\ConfigWebhookEndpointProvider;
use Rasuvaeff\Yii3Webhooks\WebhookEndpoint;

$endpointProvider = new ConfigWebhookEndpointProvider(map: [
    'order.created' => [
        new WebhookEndpoint(url: 'https://partner-a.example.com/hooks', secret: 'secret-a'),
        new WebhookEndpoint(url: 'https://partner-b.example.com/hooks', secret: 'secret-b'),
    ],
    'order.paid' => [
        new WebhookEndpoint(url: 'https://partner-a.example.com/hooks', secret: 'secret-a'),
    ],
]);

2. Wire the publisher

use Rasuvaeff\Yii3OutboxWebhooksBridge\OutboxWebhookPublisher;

$publisher = new OutboxWebhookPublisher(
    dispatcher: $dispatcher,        // your WebhookDispatcher impl
    endpointProvider: $endpointProvider,
    deliveryStorage: $deliveryStorage, // e.g. DbWebhookDeliveryStorage
);

3. Run the outbox processor

use Rasuvaeff\Yii3Outbox\Processor;

$processor = new Processor(
    storage: $outboxStorage,
    publisher: $publisher,
    clock: $clock,
);

// In a background worker or console command:
$result = $processor->process(types: ['order.created', 'order.paid']);

Behaviour

Event id dedup

The outbox message id is reused as the WebhookEvent id. On retry, the same id is sent again. Receivers should use the X-Webhook-Id header (set by HmacSha256Signer) for idempotency.

Custom endpoint provider

Implement WebhookEndpointProvider to load endpoints from a database, cache, or any runtime source:

use Rasuvaeff\Yii3OutboxWebhooksBridge\WebhookEndpointProvider;
use Rasuvaeff\Yii3Webhooks\WebhookEndpoint;

final readonly class DbWebhookEndpointProvider implements WebhookEndpointProvider
{
    public function __construct(private \PDO $db) {}

    public function getEndpointsForType(string $type): array
    {
        // load from DB...
    }
}

Security

• Secrets are never stored in WebhookDelivery (comes from yii3-webhooks).
• Use HmacSha256Signer (from yii3-webhooks) as your WebhookDispatcher's signer to authenticate outbound requests.
• Receivers should validate the signature via WebhookVerifier and use ReplayGuard against nonce replay.

Examples

See examples/ for runnable scripts.

Development

docker run --rm -v "$PWD":/app -w /app composer:2 composer build
docker run --rm -v "$PWD":/app -w /app composer:2 composer cs:fix
docker run --rm -v "$PWD":/app -w /app composer:2 composer test

License

BSD-3-Clause. See LICENSE.md.