rasuvaeff/yii3-webhooks-db

Database-backed delivery and nonce storage for rasuvaeff/yii3-webhooks

v1.0.0 2026-06-19 19:42 UTC

Requires

• php: 8.3 - 8.5
• psr/clock: ^1.0
• rasuvaeff/yii3-webhooks: ^1.0
• yiisoft/db: ^2.0
• yiisoft/db-migration: ^2.0

Requires (Dev)

• ergebnis/composer-normalize: ^2.51
• friendsofphp/php-cs-fixer: ^3.95
• infection/infection: ^0.29
• maglnet/composer-require-checker: ^4.17
• phpunit/phpunit: ^11.5
• rector/rector: ^2.4
• roave/backward-compatibility-check: ^8.0
• vimeo/psalm: ^6.16
• yiisoft/cache: ^3.2
• yiisoft/db-sqlite: ^2.0
• yiisoft/test-support: ^3.1

BSD-3-Clause

• Victor Razuvaev

• database
• db
• webhook
• yii3
• replay-protection

README

Database-backed delivery and nonce storage for rasuvaeff/yii3-webhooks. It provides production storage for delivery attempts and atomic replay protection.

Using an AI coding assistant? llms.txt has a compact API reference you can use.

Requirements

• PHP 8.3+
• rasuvaeff/yii3-webhooks ^1.0
• yiisoft/db ^2.0
• yiisoft/db-migration ^2.0
• psr/clock ^1.0

Installation

composer require rasuvaeff/yii3-webhooks-db

Usage

Run M260612000000CreateWebhookTables to create webhook_deliveries and webhook_nonces.

use Psr\Clock\ClockInterface;
use Rasuvaeff\Yii3Webhooks\WebhookDelivery;
use Rasuvaeff\Yii3WebhooksDb\DbNonceStorage;
use Rasuvaeff\Yii3WebhooksDb\DbWebhookDeliveryStorage;

$deliveries = new DbWebhookDeliveryStorage(db: $db);
$nonces = new DbNonceStorage(db: $db, clock: $clock);

$delivery = WebhookDelivery::create(event: $event, endpoint: $endpoint);
$deliveries->save(delivery: $delivery);
$accepted = $nonces->add(nonce: $signature->getValue());

With yiisoft/config, this package binds only WebhookDeliveryStorage and NonceStorage.

API reference

DbWebhookDeliveryStorage

Method	Description
save(delivery)	Inserts or updates a delivery row
findPending(limit)	Returns pending deliveries ordered by creation time
markDelivered(delivery)	Stores the delivery as delivered
markFailed(delivery)	Stores the delivery as failed
getById(id)	Loads a delivery by ID

DbNonceStorage

Method	Description
has(nonce)	Checks whether a nonce exists
add(nonce)	Atomic insert; returns false on duplicate
deleteOlderThan(threshold)	Deletes old nonces for retention cleanup

Security

• DbNonceStorage::add() relies on the primary key and catches duplicate-key errors.
• DbWebhookDeliveryStorage persists only WebhookDelivery data, never endpoint secrets.
• Keep nonce rows at least as long as your webhook timestamp tolerance window.

Examples

See examples/ for a runnable SQLite example.

Development

make install
make build
make cs-fix
make test
make test-coverage
make mutation
make release-check

License

BSD-3-Clause. See LICENSE.md.