Download the PHP package rasuvaeff/yii3-webhooks-db without Composer

rasuvaeff/yii3-webhooks-db

Русская версия

Database storage for rasuvaeff/yii3-webhooks deliveries and nonces: a production-grade record of delivery attempts and atomic replay protection.

Using an AI coding assistant? llms.txt contains a compact API reference you can share with the model.

Requirements

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

Installation

Usage

Under yiisoft/config this package binds only WebhookDeliveryStorage and NonceStorage.

More than one worker

findPending() hands the same rows to every worker that asks and knows nothing about backoff, so two workers deliver the same event twice and a backlog of deliveries waiting out their backoff fills every batch while ready ones behind them starve. claimReady() leases instead:

Ownership is a lease, not a status: a claimed delivery stays Pending and becomes claimable again once claimed_at is older than leaseSeconds, so a worker that dies strands nothing. leaseSeconds must outlive the slowest delivery attempt, or two workers get the same delivery. A delivery that is out of attempts is handed out — nothing else could ever mark it Failed.

readyThresholds() comes from WebhookRetryPolicy in rasuvaeff/yii3-webhooks; the backoff rule is the core's and is never re-derived here. Each key governs every attempt count from itself up to the next key, so a map built by hand may skip counts without stranding the deliveries that land on them.

DbWebhookDeliveryStorage declares ClaimingDeliveryStorage, which is how a worker picks the claiming path:

Retention

Nothing else in this package removes a delivery row, so the table grows for as long as the application runs:

The default statuses are the terminal ones. Passing WebhookDeliveryStatus::Pending deletes work that was never done — a decision the caller has to make out loud.

Migration

Register the bundled migration (Rasuvaeff\Yii3WebhooksDb\Migration\M260612000000CreateWebhookTables) by namespace — no vendor paths:

Two migrations live in that namespace: M260612000000CreateWebhookTables creates both tables, and M260822120000AddDeliveryClaimColumns adds the claimed_at / claimed_by columns claimReady() needs. An installation that already ran the first one only gets the second. down() on the second works on MySQL and PostgreSQL only — yiisoft/db-sqlite cannot drop a column.

yiisoft/db-migration resolves the migration through Injector::make(), so it picks up the table-name value objects from the container the same way the storages do — no manual wiring needed beyond setSourceNamespaces() above.

Set the table names in params — the same values reach the migration and both storages (as WebhookDeliveryTableName / WebhookNonceTableName):

Index names follow the table names, so two installations can share one PostgreSQL schema — index names are unique per schema there, not per table.

Do not configure the migration through the DI container. M...::class => ['__construct()' => [...]] does not work: the migration is built by Injector::make(), which resolves arguments by type and never reads a container definition keyed by the migration's own class. Worse, adding that definition makes the container fatal at build time in every request, because the class is not autoloadable until the migration runner requires it. That recipe was documented in 1.x; it never worked.

API reference

DbWebhookDeliveryStorage

DbNonceStorage

Security

• DbNonceStorage::add() relies on the primary key and catches duplicate-key errors — that is what makes replay protection atomic instead of a check-then-write race.
• DbWebhookDeliveryStorage persists WebhookDelivery fields only; endpoint secrets are never stored.
• Keep nonce rows for at least the webhook timestamp tolerance window: prune them sooner and a replay becomes possible again.
• With more than one worker, use claimReady(). findPending() gives every worker the same rows, and the receiver sees the same event delivered twice.
• endpoint_url is stored verbatim. WebhookEndpoint refuses credentials in the URL, so nothing new can put a secret there — but rows written by an older core version may still carry https://user:pass@host/. Audit the column once and rewrite what you find; use endpoint headers for authentication, they never reach the database.

Examples

See examples/ for a runnable SQLite example.

Development

License

BSD-3-Clause. See LICENSE.md.