@nestarc/webhook 0.13.1 → 0.13.2

package/README.md

@@ -1,72 +1,71 @@
-# @nestarc/webhook
+# @nestarc/webhook — Outbound webhooks for NestJS
 
-Outbound webhook delivery for NestJS — HMAC signing, exponential retry, circuit breaker, delivery logs, fan-out, [Standard Webhooks](https://www.standardwebhooks.com/) compatible.
-
-**No separate infrastructure required.** Uses your existing PostgreSQL database.
+Send signed webhook events from a NestJS application using PostgreSQL as the delivery queue. Includes fan-out, retries, endpoint circuit breaking, and delivery history. The default adapters use Prisma and Node.js HTTP; no separate message broker is required.
 
 [![CI](https://github.com/nestarc/webhook/actions/workflows/ci.yml/badge.svg)](https://github.com/nestarc/webhook/actions/workflows/ci.yml)
 
-[Changelog](./CHANGELOG.md) · [Security policy](./SECURITY.md)
+[Documentation](https://nestarc.dev/packages/webhook/) · [API Reference](https://nestarc.dev/api/webhook/) · [npm](https://www.npmjs.com/package/@nestarc/webhook) · [Changelog](./CHANGELOG.md) · [Security policy](./SECURITY.md)
+
+> **Version scope:** This README describes `0.13.2`; see its [changes](./CHANGELOG.md#0132---2026-09-11). If that version is not yet available on npm, use a locally packed build from this checkout. Before `1.0.0`, minor releases may contain breaking changes; review the changelog and pin exact versions.
+
+## Contents
 
-> **Pre-1.0:** minor version bumps may include breaking changes. Pin exact versions in production until `1.0.0`.
+- [Features](#features)
+- [Requirements and installation](#requirements-and-installation)
+- [Database setup](#database-setup)
+- [Quick start](#quick-start)
+- [Publishing and delivery guarantees](#publishing-and-delivery-guarantees)
+- [API reference](#api-reference)
+- [Configuration](#configuration)
+- [Retries, replay, and delivery history](#retries-replay-and-delivery-history)
+- [Security and receiving webhooks](#security-and-receiving-webhooks)
+- [Worker separation](#worker-separation)
+- [Using this package with an AI agent](#using-this-package-with-an-ai-agent)
 
 ## Features
 
-- **Fan-out delivery** — one event to many endpoints
-- **Idempotent publish** — deduplicate producer retries with application keys
-- **HMAC-SHA256 signing** — Standard Webhooks compatible headers
-- **Secret rotation overlap** — sign with both old and new secrets during rotation windows
-- **Exponential backoff** — 30s, 5m, 30m, 2h, 24h (with jitter)
-- **Circuit breaker** — auto-disable failing endpoints, auto-recover after cooldown
-- **Dead letter queue** — failed deliveries tracked for manual retry
-- **Delivery logs** — full audit trail (status code, latency, response body)
-- **Per-attempt audit log** — every attempt recorded with status, latency, response body, and errors
-- **Replay and bulk retry** — requeue failed deliveries or replay an event to active endpoints
-- **Retention and redaction controls** — purge stored payloads/response bodies and sanitize data before persistence
-- **Endpoint snapshotting** — queued deliveries keep their original URL and signing secret during retries
-- **Multi-instance safe** — `FOR UPDATE SKIP LOCKED` prevents duplicate delivery
-- **Graceful shutdown** — waits for in-flight deliveries on process exit
-- **SSRF defense** — DNS resolution validation at registration and dispatch time
-- **Ports/adapters architecture** — swap Prisma or fetch with custom implementations
-- **Stale delivery recovery** — lease-based reaper recovers crashed worker deliveries
-- **Notification hooks** — retry, degraded, failed, and disabled callbacks for observability and alerting
-
-## Installation
+- Fan-out to subscribed endpoints, with tenant-scoped and explicitly targeted publishing.
+- Producer idempotency keys that avoid creating duplicate events and delivery rows.
+- HMAC-SHA256 signatures using the Standard Webhooks signing format and headers.
+- Scheduled retries with jitter, failed-delivery retry, and event replay.
+- Endpoint circuit breaker, recovery cooldown, and notification hooks.
+- Delivery status plus per-attempt history, with retention and redaction controls.
+- Queued destination and signing-secret snapshots, including rotation overlap.
+- Concurrent worker claiming with `FOR UPDATE SKIP LOCKED`, stale-claim recovery, and graceful shutdown.
+- URL and DNS validation against SSRF, plus configurable repository, HTTP, and secret-vault adapters.
+
+## Requirements and installation
+
+You need an existing NestJS application, a PostgreSQL database, and a running API process or separate delivery worker. The package supports Node.js 20+, NestJS 10 or 11, `@nestjs/schedule` 4 or 5, and Prisma Client 5, 6, or 7. Respect the stricter requirements of your selected dependencies: Prisma 7.10.0 requires Node.js `^20.19`, `^22.12`, or `>=24.0` and TypeScript 5.4+.
+
+Install the package into your application:
 
 ```bash
-npm install @nestarc/webhook
+npm install --save-exact @nestarc/webhook@0.13.2
 ```
 
-**Peer dependencies:**
+Keep existing compatible NestJS and Prisma dependencies. For a NestJS 11 / Prisma 7 setup, the following exact versions are covered by the repository's compatibility checks:
 
 ```bash
-npm install @nestjs/common @nestjs/core @nestjs/schedule @prisma/client
+npm install --save-exact @nestjs/common@11.2.1 @nestjs/core@11.2.1 @nestjs/schedule@5.0.1 @prisma/client@7.10.0 @prisma/adapter-pg@7.10.0 pg@8.23.0
+npm install reflect-metadata rxjs dotenv
+npm install --save-dev --save-exact prisma@7.10.0 @types/pg@8.23.1
 ```
 
-Supported peer ranges are NestJS 10 or 11, `@nestjs/schedule` 4 or 5, and
-Prisma Client 5, 6, or 7. The CI compatibility lanes keep the established
-NestJS 10.4.20/Prisma 6.19.3 path and separately exercise the modern
-NestJS 11.2.1/Prisma 7.10.0 path against PostgreSQL 16. A packed-artifact
-consumer also installs the modern tuple with `--strict-peer-deps` and verifies
-artifact integrity/provenance, public types, and CommonJS runtime loading.
-The Prisma 6 lane deliberately retains `prisma-client-js` and native
-`new PrismaClient()` construction; only the Prisma 7 lane uses a driver adapter.
+Prisma 5 and 6 applications can keep their existing generated client and `new PrismaClient()` construction. CI exercises NestJS 10/11 with Prisma 6, and NestJS 11 with Prisma 7, against PostgreSQL 16; support for a declared peer range does not mean every version combination is tested.
 
 ### Prisma 7 client setup
 
-Prisma 7 requires a database driver adapter. Configure and generate the client
-in your application, then pass that client to `WebhookModule`; this package
-does not create or own your Prisma connection.
+The default repositories use Prisma's raw-query and transaction APIs. Webhook tables are created by the SQL below; adding webhook models to your Prisma schema is unnecessary. The application owns the Prisma connection and must disconnect it during shutdown.
 
-```bash
-npm install @prisma/adapter-pg pg
-```
+For a NestJS application compiled to CommonJS:
 
 ```prisma
 // prisma/schema.prisma
 generator client {
-  provider = "prisma-client"
-  output   = "../src/generated/prisma"
+  provider     = "prisma-client"
+  output       = "../src/generated/prisma"
+  moduleFormat = "cjs"
 }
 
 datasource db {
@@ -76,6 +75,7 @@ datasource db {
 
 ```typescript
 // prisma.config.ts
+import 'dotenv/config';
 import { defineConfig, env } from 'prisma/config';
 
 export default defineConfig({
@@ -84,100 +84,83 @@ export default defineConfig({
 });
 ```
 
+Set the same connection string for Prisma, the application, and `psql`:
+
+```bash
+export DATABASE_URL='postgresql://user:password@localhost:5432/your_database'
+npx prisma generate
+```
+
+Alternatively, store `DATABASE_URL` in your application's uncommitted `.env` file. The `dotenv/config` imports load it for Prisma and the application; export the variable in your shell before running the `psql` commands below.
+
 ```typescript
+// src/prisma.ts
+import 'dotenv/config';
 import { PrismaPg } from '@prisma/adapter-pg';
 import { PrismaClient } from './generated/prisma/client';
 
-const adapter = new PrismaPg({
-  connectionString: process.env.DATABASE_URL!,
-});
-const prisma = new PrismaClient({ adapter });
+if (!process.env.DATABASE_URL) throw new Error('DATABASE_URL is required');
 
-WebhookModule.forRoot({ prisma });
+export const prisma = new PrismaClient({
+  adapter: new PrismaPg({ connectionString: process.env.DATABASE_URL }),
+});
 ```
 
-Prisma 5 and 6 consumers can keep their existing client construction. The
-default webhook repositories only require Prisma's raw-query and transaction
-surface, so applications may also provide a compatible custom Prisma service.
+For NestJS dependency injection and connection lifecycle management, pass your existing `PrismaService` through [async configuration](#async-configuration). A complete executable receiver and producer are in the [quick-start example](./examples/quick-start/README.md).
 
-## Database Setup
+## Database setup
 
-Run the migration SQL against your PostgreSQL database:
+For a **new database**, run the full schema once before starting the module:
 
 ```bash
-psql -d your_database -f node_modules/@nestarc/webhook/src/sql/create-webhook-tables.sql
+psql "$DATABASE_URL" -v ON_ERROR_STOP=1 -f node_modules/@nestarc/webhook/src/sql/create-webhook-tables.sql
 ```
 
-This creates four tables: `webhook_endpoints`, `webhook_events`, `webhook_deliveries`, and `webhook_delivery_attempts`.
+This creates `webhook_endpoints`, `webhook_events`, `webhook_deliveries`, and `webhook_delivery_attempts`, including current indexes. The SQL includes `CREATE EXTENSION IF NOT EXISTS pgcrypto` for PostgreSQL versions before 13; the migration user needs permission to create the extension if it is absent.
 
-The migration includes `CREATE EXTENSION IF NOT EXISTS pgcrypto` for PostgreSQL < 13 compatibility.
+For an **existing installation**, apply every migration newer than your installed schema, in ascending order. Re-running the full schema does not add missing columns to existing tables.
 
-### Upgrading from versions before 0.9.0
+| Existing schema version | Required migration sequence |
+|---|---|
+| Before `0.9.0` | `v0.9.0.sql` → `v0.12.0.sql` → `v0.13.0.sql` |
+| `0.9.x`–`0.11.x` | `v0.12.0.sql` → `v0.13.0.sql` |
+| `0.12.x` | `v0.13.0.sql` |
+| `0.13.x` | No additional migration for the changes documented here |
 
-Existing databases need the v0.9.0 additive migration for per-attempt audit logs, endpoint snapshots, and secret rotation overlap:
+For example, upgrading from a schema before `0.9.0`:
 
 ```bash
-psql -d your_database -f node_modules/@nestarc/webhook/src/sql/migrations/v0.9.0.sql
+psql "$DATABASE_URL" -v ON_ERROR_STOP=1 -f node_modules/@nestarc/webhook/src/sql/migrations/v0.9.0.sql
+psql "$DATABASE_URL" -v ON_ERROR_STOP=1 -f node_modules/@nestarc/webhook/src/sql/migrations/v0.12.0.sql
+psql "$DATABASE_URL" -v ON_ERROR_STOP=1 -f node_modules/@nestarc/webhook/src/sql/migrations/v0.13.0.sql
 ```
 
-See [CHANGELOG.md](./CHANGELOG.md) for release-specific migration notes.
+`v0.9.0` adds attempt history, snapshots, and secret rotation; `v0.12.0` adds worker indexes; `v0.13.0` adds idempotency, correlation, and payload-purge metadata. See the [changelog](./CHANGELOG.md) before each upgrade.
 
-### Upgrading from versions before 0.13.0
+## Quick start
 
-Existing databases need the v0.13.0 additive migration for idempotent publish keys, correlation IDs, and payload purge metadata:
-
-```bash
-psql -d your_database -f node_modules/@nestarc/webhook/src/sql/migrations/v0.13.0.sql
-```
-
-## Quick Start
+For a complete local flow that starts a receiver, publishes an event, verifies its signature, and checks delivery status, run the [quick-start example](./examples/quick-start/README.md). The snippets below show integration into an existing NestJS application.
 
 ### 1. Register the module
 
 ```typescript
+// src/app.module.ts
+import { Module } from '@nestjs/common';
 import { WebhookModule } from '@nestarc/webhook';
+import { prisma } from './prisma';
 
 @Module({
-  imports: [
-    WebhookModule.forRoot({
-      // prismaService is your PrismaClient/PrismaService instance.
-      // See "Async configuration" below for NestJS DI wiring.
-      prisma: prismaService,
-      delivery: {
-        timeout: 30_000,
-        maxRetries: 6,
-        jitter: true,
-      },
-      circuitBreaker: {
-        degradedThreshold: 3,
-        failureThreshold: 5,
-        cooldownMinutes: 60,
-      },
-      polling: {
-        interval: 5000,
-        batchSize: 50,
-      },
-      onDeliveryRetryScheduled: (ctx) => {
-        // Internal observability: a retry was persisted with ctx.nextAttemptAt.
-      },
-      onEndpointDegraded: (ctx) => {
-        // Alert candidate: endpoint reached the degraded threshold before disablement.
-      },
-      onDeliveryFailed: (ctx) => {
-        // Terminal delivery failure only.
-      },
-      onEndpointDisabled: (ctx) => {
-        // Endpoint transitioned from active to inactive.
-      },
-    }),
-  ],
+  imports: [WebhookModule.forRoot({ prisma })],
 })
 export class AppModule {}
 ```
 
-### 2. Define events
+Polling is enabled by default. Keep the Nest application running so queued deliveries can be processed.
+
+### 2. Define an event
 
 ```typescript
+// src/order-created.event.ts
 import { WebhookEvent } from '@nestarc/webhook';
 
 export class OrderCreatedEvent extends WebhookEvent {
@@ -192,147 +175,145 @@ export class OrderCreatedEvent extends WebhookEvent {
 }
 ```
 
-> **Note:** Subclasses **must** define `static readonly eventType`. The module throws at runtime if this is missing.
+Each subclass must define `static readonly eventType`; publishing throws if it is missing. Enumerable instance properties become `data` in the delivered JSON:
 
-### 3. Send events
-
-```typescript
-import { WebhookService } from '@nestarc/webhook';
-
-@Injectable()
-export class OrderService {
-  constructor(private readonly webhooks: WebhookService) {}
-
-  async createOrder(dto: CreateOrderDto) {
-    const order = await this.saveOrder(dto);
-    await this.webhooks.send(new OrderCreatedEvent(order.id, order.total));
-    return order;
-  }
+```json
+{
+  "type": "order.created",
+  "data": { "orderId": "ord_123", "total": 99.99 }
 }
 ```
 
-Use an idempotency key when the producer may retry the same business operation:
+### 3. Register the receiver before publishing
+
+Inject `WebhookEndpointAdminService` into your application's endpoint-registration service and call:
 
 ```typescript
-await this.webhooks.send(new OrderCreatedEvent(order.id, order.total), {
-  idempotencyKey: `order:${order.id}:created`,
-  correlationId: requestId,
+const endpoint = await endpointAdmin.createEndpoint({
+  url: 'https://customer.com/webhooks', // Replace with your receiver URL.
+  events: ['order.created'],          // Use ['*'] to subscribe to every event type.
+  tenantId: 'tenant_123',
+  secret: 'auto',                     // Omit for the same automatic generation.
 });
 ```
 
-Duplicate sends with the same tenant, event type, and idempotency key return the existing event ID and do not enqueue duplicate deliveries.
+Provision `endpoint.secret` to the receiver through your application's secure setup flow, then publish. Signing secrets are returned by creation and rotation; list/get APIs omit them. `tenantId` is optional and is stored as `null` when omitted.
 
-### 4. Manage endpoints
+### 4. Publish and check delivery
+
+Register this service in the `providers` of an application module:
 
 ```typescript
-import { WebhookEndpointAdminService } from '@nestarc/webhook';
+import { Injectable } from '@nestjs/common';
+import { WebhookDeliveryAdminService, WebhookService } from '@nestarc/webhook';
+import { OrderCreatedEvent } from './order-created.event';
 
 @Injectable()
-export class WebhookController {
-  constructor(private readonly endpointAdmin: WebhookEndpointAdminService) {}
-
-  async register() {
-    // Secret is returned only on creation
-    return this.endpointAdmin.createEndpoint({
-      url: 'https://customer.com/webhooks',
-      events: ['order.created', 'order.paid'],
-      tenantId: 'tenant_123', // optional; omit for global endpoints (returned as null)
-      secret: 'auto', // case-sensitive; omit or pass "auto" to generate a secret
-    });
+export class OrderWebhookService {
+  constructor(
+    private readonly webhooks: WebhookService,
+    private readonly deliveryAdmin: WebhookDeliveryAdminService,
+  ) {}
+
+  async publish(tenantId: string, orderId: string, total: number) {
+    return this.webhooks.sendToTenant(
+      tenantId,
+      new OrderCreatedEvent(orderId, total),
+      { idempotencyKey: `order:${orderId}:created` },
+    );
+  }
+
+  async deliveryHistory(endpointId: string) {
+    return this.deliveryAdmin.getDeliveryLogs(endpointId);
   }
 }
 ```
 
-## API Reference
+The returned string is the **event ID after the event and delivery rows commit**, not confirmation of HTTP delivery. After the worker polls, use delivery history to check `SENT`, `FAILED`, `PENDING`, or `SENDING`; match the returned event ID against `DeliveryRecord.eventId`. [Receiver verification](#signing-and-receiver-verification) uses that same ID in the `webhook-id` header.
+
+If no active endpoints match when you publish, the event is saved with **zero deliveries**. Registering an endpoint later does not automatically deliver earlier events; use explicit replay if required.
 
-### WebhookService
+## Publishing and delivery guarantees
 
-| Method | Description |
-|--------|-------------|
-| `send(event)` | Publish event to all matching endpoints |
-| `sendToTenant(tenantId, event)` | Publish to tenant-specific endpoints only |
-| `sendToEndpoints(endpointIds, event)` | Publish to specific endpoint IDs only |
+The default Prisma repositories persist an event and its initial delivery rows in one transaction. That transaction is separate from your application's order/payment transaction; the public publish API does not accept an existing business transaction. If both writes must succeed atomically, design an application outbox or a custom integration around that requirement.
 
-All publish methods accept optional `WebhookPublishOptions` with `idempotencyKey` and `correlationId`.
+| Publish method | Endpoint scope |
+|---|---|
+| `send(event, options?)` | All active matching endpoints, **across all tenants**, including endpoints with no tenant |
+| `sendToTenant(tenantId, event, options?)` | Active matching endpoints belonging to that tenant only; excludes endpoints with no tenant |
+| `sendToEndpoints(ids, event, options?)` | Active matching endpoints among the IDs, across tenants |
+| `sendToEndpoints(ids, event, tenantId, options?)` | Active matching endpoints among the IDs, restricted to that tenant |
+
+An endpoint matches when its subscriptions contain the event type or `'*'`. An empty ID list saves the event without creating deliveries. These methods are application services: authenticate callers and enforce tenant authorization before invoking them.
 
-### WebhookEndpointAdminService
+All publish methods accept `WebhookPublishOptions`:
 
-| Method | Description |
-|--------|-------------|
-| `createEndpoint(dto)` | Register a new webhook endpoint (returns secret) |
-| `listEndpoints(tenantId?)` | List all endpoints (secret excluded) |
-| `getEndpoint(id)` | Get endpoint details (secret excluded) |
-| `updateEndpoint(id, dto)` | Update endpoint URL, events, description, metadata, or active status |
-| `rotateSecret(endpointId, dto)` | Rotate the endpoint signing secret and keep the previous secret valid until `previousSecretExpiresAt` |
-| `deleteEndpoint(id)` | Delete an endpoint |
-| `sendTestEvent(endpointId)` | Send a `webhook.test` ping event |
+```typescript
+await webhooks.sendToTenant('tenant_123', event, {
+  idempotencyKey: 'order:ord_123:created',
+  correlationId: 'request_456',
+});
+```
 
-### WebhookDeliveryAdminService
+The default adapter deduplicates by tenant, event type, and idempotency key. Reusing a key returns the original event ID without updating its payload, correlation ID, or endpoint selection. Producer idempotency does not prevent duplicate HTTP requests. Correlation IDs are stored for diagnostics and are not added to the delivered payload or headers. Independent `correlationId` persistence, without an idempotency key, is supported from [0.13.2](./CHANGELOG.md#0132---2026-09-11).
 
-| Method | Description |
-|--------|-------------|
-| `getDeliveryLogs(endpointId, filters?)` | Query delivery history |
-| `getDeliveryAttempts(deliveryId)` | Query per-attempt audit records for a delivery |
-| `retryDelivery(deliveryId)` | Manually retry a failed delivery |
-| `retryFailedDeliveries(filters, options?)` | Requeue matching failed deliveries in bulk |
-| `replayEvent(eventId, options?)` | Create new delivery rows for an existing event and currently active endpoints |
+Delivery uses retries with a finite attempt budget. `FOR UPDATE SKIP LOCKED` prevents workers from claiming the same pending row concurrently, but it does not guarantee exactly-once delivery. If a receiver processes a request and the worker fails before saving success, the request can be sent again. A receiver must deduplicate `webhook-id` within its own processing scope and make its business side effects idempotent. Delivery can still end in `FAILED` after permanent errors or exhausted attempts, and ordering between events is not guaranteed.
 
-### WebhookRetentionAdminService
+## API reference
 
-| Method | Description |
-|--------|-------------|
-| `purgeExpiredData(now?)` | Apply configured retention policy and return purge counts |
+See the [full API reference](https://nestarc.dev/api/webhook/) and [consumer guide](./docs/usage.md) for type definitions, return values, errors, and operational examples. The installed package includes TypeScript declarations under `dist/`.
 
-### WebhookSigner
+| Service | Methods |
+|---|---|
+| `WebhookService` | `send`, `sendToTenant`, `sendToEndpoints` |
+| `WebhookEndpointAdminService` | `createEndpoint`, `listEndpoints`, `getEndpoint`, `updateEndpoint`, `rotateSecret`, `deleteEndpoint`, `sendTestEvent` |
+| `WebhookDeliveryAdminService` | `getDeliveryLogs`, `getDeliveryAttempts`, `retryDelivery`, `retryFailedDeliveries`, `replayEvent` |
+| `WebhookRetentionAdminService` | `purgeExpiredData` |
+| `WebhookSigner` | `sign`, `signAll`, `verify`, `verifyWithTolerance`, `generateSecret` |
 
-| Method | Description |
-|--------|-------------|
-| `sign(eventId, timestamp, body, secret)` | Generate Standard Webhooks signature headers |
-| `signAll(eventId, timestamp, body, secrets[])` | Generate multi-signature headers for secret rotation overlap |
-| `verify(eventId, timestamp, body, secret, signature)` | Verify a webhook signature |
-| `verifyWithTolerance(eventId, timestamp, body, secret, signature, options)` | Verify a signature and reject timestamps outside `options.toleranceSeconds` |
-| `generateSecret()` | Generate a random base64 signing secret |
+`listEndpoints()` lists all tenants; `listEndpoints(tenantId)` filters to one. Endpoint reads omit signing secrets. `sendTestEvent(endpointId)` queues a `webhook.test` event with a single attempt and returns its event ID, or `null` if the endpoint does not exist. This explicit diagnostic operation bypasses active-state and subscription matching.
 
-> **Deprecated:** `WebhookAdminService` is a facade that delegates to `WebhookEndpointAdminService` and `WebhookDeliveryAdminService`. It has been deprecated since `v0.2.0` and will be removed in `v1.0.0`.
+`WebhookAdminService` is a deprecated facade over the endpoint and delivery admin services, deprecated since `0.2.0` and scheduled for removal in `1.0.0`.
 
 ## Configuration
 
 | Option | Default | Description |
-|--------|---------|-------------|
-| `prisma` | — | PrismaClient instance (required unless all custom repos provided) |
-| `delivery.timeout` | `10000` | HTTP request timeout (ms) |
-| `delivery.maxRetries` | `5` | Maximum delivery attempts |
-| `delivery.jitter` | `true` | Add random jitter to retry delays |
-| `circuitBreaker.failureThreshold` | `5` | Consecutive failures before disabling endpoint |
-| `circuitBreaker.degradedThreshold` | — | Consecutive failures before firing `onEndpointDegraded`. Disabled unless configured. Must be lower than `failureThreshold`. |
-| `circuitBreaker.cooldownMinutes` | `60` | Minutes before attempting recovery |
-| `polling.enabled` | `true` | Set to `false` to disable the polling loop (API-only mode) |
-| `polling.interval` | `5000` | Delivery worker poll interval (ms) |
-| `polling.batchSize` | `50` | Max rows claimed in one database claim |
-| `polling.staleSendingMinutes` | `5` | Minutes before a stuck SENDING delivery is recovered |
-| `polling.maxConcurrency` | `polling.batchSize` | Max delivery dispatches in flight per worker process |
-| `polling.drainWhileBacklogged` | `false` | Keep claiming additional batches inside one poll while backlog and capacity remain |
-| `polling.maxDrainLoopsPerPoll` | `1`, or `10` when drain mode is enabled | Max claim loops inside one poll cycle |
-| `polling.drainLoopDelayMs` | `0` | Optional delay between drain loops |
-| `retention.eventPayloadRetentionDays` | — | Replace terminal event payloads with `{}` after this many days. Disabled unless set. |
-| `retention.deliveryResponseBodyRetentionDays` | — | Clear terminal delivery response bodies after this many days. Disabled unless set. |
-| `retention.attemptResponseBodyRetentionDays` | — | Clear attempt response bodies after this many days. Disabled unless set. |
-| `redaction.sanitizePayload` | — | Minimize payload before persistence and delivery. This changes delivered content. |
-| `redaction.sanitizeResponseBody` | — | Sanitize or suppress response bodies before storing delivery and attempt rows. |
-| `allowPrivateUrls` | `false` | Allow private/internal URLs (dev/test only) |
-| `secretVault` | `PlaintextSecretVault` | Custom vault for encrypting/decrypting endpoint secrets at rest |
-| `onDeliveryFailed` | — | Fire-and-forget callback when a delivery exhausts retries or receives a non-retryable response. Receives `DeliveryFailedContext` (`tenantId` is `null` for global endpoints). See **Delivery failure classification** below. |
-| `onDeliveryRetryScheduled` | — | Fire-and-forget callback after a retriable failed attempt is persisted with `nextAttemptAt`. Receives `DeliveryRetryScheduledContext`. Does not fire for terminal failures. |
-| `onEndpointDegraded` | — | Fire-and-forget callback when consecutive failures reach `circuitBreaker.degradedThreshold` before endpoint disablement. Receives `EndpointDegradedContext`. |
-| `onEndpointDisabled` | — | Fire-and-forget callback when the circuit breaker disables an endpoint. Fires only on active-to-inactive transition after failures meet or exceed `failureThreshold`. |
-
-The retry schedule is fixed exponential (`30s`, `5m`, `30m`, `2h`, `24h`). Use `delivery.jitter` to enable or disable random jitter.
-
-### Worker Capacity And Observer Metrics
-
-The delivery worker keeps the previous default behavior: one poll claims up to `polling.batchSize` rows and waits for those deliveries before the next interval. Set `polling.maxConcurrency` to cap in-flight dispatches below or above a claim size, and set `polling.drainWhileBacklogged: true` when a worker should continue draining queued deliveries inside the same poll cycle.
-
-```ts
+|---|---|---|
+| `prisma` | — | Application-owned Prisma client; required unless all three custom repositories are supplied |
+| `delivery.timeout` | `10000` | HTTP request timeout in milliseconds |
+| `delivery.maxRetries` | `5` | **Total attempt budget, including the first request** |
+| `delivery.jitter` | `true` | Add random jitter to the fixed retry schedule |
+| `circuitBreaker.failureThreshold` | `5` | Consecutive failures before disabling an endpoint |
+| `circuitBreaker.degradedThreshold` | — | Failure count for `onEndpointDegraded`; must be lower than `failureThreshold` |
+| `circuitBreaker.cooldownMinutes` | `60` | Minutes before automatic recovery of circuit-disabled endpoints |
+| `polling.enabled` | `true` | Enable delivery polling; set `false` for an API-only process |
+| `polling.interval` | `5000` | Poll interval in milliseconds |
+| `polling.batchSize` | `50` | Maximum rows claimed in one database claim |
+| `polling.staleSendingMinutes` | `5` | Age of a `SENDING` claim before recovery |
+| `polling.maxConcurrency` | `polling.batchSize` | Maximum in-flight dispatches per worker process |
+| `polling.drainWhileBacklogged` | `false` | Claim more batches within a poll while backlog and capacity remain |
+| `polling.maxDrainLoopsPerPoll` | `1`, or `10` with drain mode | Maximum claim loops per poll |
+| `polling.drainLoopDelayMs` | `0` | Delay between drain loops in milliseconds |
+| `workerObserver` | — | Best-effort poll and delivery metrics callbacks |
+| `retention.eventPayloadRetentionDays` | — | Replace eligible terminal event payloads with `{}` after this many days |
+| `retention.deliveryResponseBodyRetentionDays` | — | Clear eligible terminal delivery response bodies after this many days |
+| `retention.attemptResponseBodyRetentionDays` | — | Clear eligible attempt response bodies after this many days |
+| `redaction.sanitizePayload` | — | Transform payload before persistence **and delivery** |
+| `redaction.sanitizeResponseBody` | — | Sanitize or suppress response bodies before persistence |
+| `allowPrivateUrls` | `false` | Permit private/internal URLs; use only in controlled development/tests |
+| `secretVault` | `PlaintextSecretVault` | Adapter for protecting signing secrets at rest |
+| `eventRepository`, `endpointRepository`, `deliveryRepository` | Prisma adapters | Replace persistence ports |
+| `httpClient` | `FetchHttpClient` | Replace HTTP transport; the default uses Node.js `http`/`https` |
+| `onDeliveryFailed` | — | Terminal delivery failure callback |
+| `onDeliveryRetryScheduled` | — | Callback after a failed attempt and its next retry time are persisted |
+| `onEndpointDegraded` | — | Callback when an active endpoint reaches the configured degraded threshold |
+| `onEndpointDisabled` | — | Callback when circuit breaking transitions an endpoint from active to inactive |
+
+### Worker capacity and metrics
+
+The default poll claims one batch and waits for its deliveries. Enable drain mode when a worker should claim additional batches within a poll:
+
+```typescript
 WebhookModule.forRoot({
   prisma,
   polling: {
@@ -344,57 +325,25 @@ WebhookModule.forRoot({
   },
   workerObserver: {
     onPollComplete(result) {
-      metrics.count('webhook.worker.claimed', result.claimed);
-      metrics.count('webhook.worker.sent', result.sent);
-      metrics.count('webhook.worker.retried', result.retried);
-      metrics.gauge('webhook.worker.poll.duration_ms', result.durationMs);
+      console.log({ claimed: result.claimed, sent: result.sent, durationMs: result.durationMs });
     },
     onDeliveryComplete(result) {
-      metrics.count(`webhook.delivery.${result.status}`, 1);
+      console.log({ deliveryId: result.deliveryId, status: result.status });
     },
     onPollError(error) {
-      logger.error({ error }, 'webhook worker poll failed');
+      console.error('Webhook worker poll failed', error);
     },
   },
 });
 ```
 
-Observer callbacks are best-effort. Exceptions thrown by observer callbacks are logged and do not fail delivery processing.
-
-Backlog diagnostics are available on repository implementations that support `getBacklogSummary()`:
-
-```ts
-const summary = await deliveryRepository.getBacklogSummary?.();
-```
-
-The summary includes `pendingCount`, `sendingCount`, `runnablePendingCount`, `oldestPendingAgeMs`, and `oldestRunnableAgeMs`.
-
-### Manual Retry, Bulk Retry, And Replay
-
-```ts
-await deliveryAdmin.retryDelivery(deliveryId, {
-  reason: 'customer requested retry',
-});
-
-await deliveryAdmin.retryFailedDeliveries({
-  endpointId,
-  eventType: 'order.created',
-  limit: 100,
-});
-
-await deliveryAdmin.replayEvent(eventId, {
-  tenantId: 'tenant_123',
-  reason: 'customer support replay',
-});
-```
-
-Manual retries only requeue failed deliveries. Event replay reuses the original event ID and creates new delivery rows for currently active matching endpoints using their current URL and signing secret snapshots.
+Observer exceptions are logged and do not fail delivery processing. Repositories that implement optional `getBacklogSummary()` expose `pendingCount`, `sendingCount`, `runnablePendingCount`, `oldestPendingAgeMs`, and `oldestRunnableAgeMs`.
 
-### Retention And Redaction
+### Retention and redaction
 
-Retention is disabled unless configured. Applications can call `WebhookRetentionAdminService.purgeExpiredData()` from their own scheduler:
+Retention is disabled by default and has no built-in purge schedule. Call `WebhookRetentionAdminService.purgeExpiredData()` from your application's scheduler after configuring a policy:
 
-```ts
+```typescript
 WebhookModule.forRoot({
   prisma,
   retention: {
@@ -404,7 +353,8 @@ WebhookModule.forRoot({
   },
   redaction: {
     sanitizePayload(payload) {
-      return { ...payload, email: undefined };
+      const { email, ...remaining } = payload;
+      return remaining;
     },
     sanitizeResponseBody() {
       return null;
@@ -413,150 +363,127 @@ WebhookModule.forRoot({
 });
 ```
 
-`sanitizePayload` runs before persistence and dispatch, so it changes the delivered webhook payload. Review retention and redaction policies with your security and legal teams before storing sensitive data.
-
-Webhook receiver responses are classified before scheduling another attempt:
-
-| Response | Behavior |
-|---|---|
-| `2xx` | Mark delivery `SENT` |
-| `3xx` | Retry while attempts remain |
-| `408`, `409`, `425`, `429` | Retry while attempts remain |
-| Other `4xx` | Mark delivery `FAILED` after the current attempt |
-| `5xx` | Retry while attempts remain |
-| Network, DNS, timeout, or dispatch error | Retry while attempts remain |
-
-Permanent `4xx` failures still record the response status/body, append a failed attempt log, count as a circuit-breaker failure, clear `nextAttemptAt`, and trigger `onDeliveryFailed`.
-
-**Delivery failure classification.** `DeliveryFailedContext.failureKind` categorizes why a delivery was abandoned after retries are exhausted or a non-retryable receiver response is observed:
-
-| `failureKind` | When | Extra fields |
-|---|---|---|
-| `url_validation` | SSRF defense rejected the URL (private, loopback, link-local, etc.) | `validationReason`, `validationUrl`, `resolvedIp` |
-| `dispatch_error` | Dispatcher threw (DNS failure, ECONNREFUSED, timeout) | — |
-| `http_error` | Endpoint responded with non-2xx status | `responseStatus` |
-
-Retryable HTTP responses only trigger `onDeliveryFailed` after the attempt budget is exhausted. Non-retryable receiver responses trigger it after the current attempt. Callback errors are logged and never change persisted delivery state.
-
-`onDeliveryRetryScheduled` fires earlier, after a retryable failed attempt has been persisted with its next attempt time. It is intended for internal observability and includes the same failure classification fields as `DeliveryFailedContext`, plus `nextAttemptAt`.
-
-`onEndpointDegraded` fires only when `circuitBreaker.degradedThreshold` is configured, the endpoint is still active, and the consecutive failure count exactly reaches that degraded threshold. It does not replace `onEndpointDisabled`, which still fires only when the endpoint transitions from active to inactive at `failureThreshold`.
-
-```ts
-onDeliveryFailed: (ctx) => {
-  if (ctx.failureKind === 'url_validation') {
-    // ctx.validationReason: 'private' | 'loopback' | 'link_local' | ...
-    alerting.endpointMisconfigured(ctx.endpointId, ctx.validationReason);
-  } else if (ctx.failureKind === 'http_error') {
-    alerting.downstreamUnhealthy(ctx.endpointId, ctx.responseStatus);
-  }
-}
-```
+Payload redaction changes what the receiver gets. Purging clears stored content; it does not delete the event/delivery metadata or idempotency key. Purged payloads cannot be replayed. From [0.13.2](./CHANGELOG.md#0132---2026-09-11), manual retries also reject deliveries whose event payload has been purged.
 
 ### Custom adapters
 
-Replace default Prisma or fetch implementations by providing custom ports:
-
 ```typescript
 WebhookModule.forRoot({
-  prisma: prismaService,
-  httpClient: myCustomHttpClient,          // implements WebhookHttpClient
-  eventRepository: myCustomEventRepo,      // implements WebhookEventRepository
-  endpointRepository: myCustomEndpointRepo,// implements WebhookEndpointRepository
-  deliveryRepository: myCustomDeliveryRepo,// implements WebhookDeliveryRepository
-  secretVault: myCustomVault,              // implements WebhookSecretVault
+  eventRepository: myEventRepository,       // WebhookEventRepository
+  endpointRepository: myEndpointRepository, // WebhookEndpointRepository
+  deliveryRepository: myDeliveryRepository,// WebhookDeliveryRepository
+  httpClient: myHttpClient,                 // WebhookHttpClient
+  secretVault: mySecretVault,               // WebhookSecretVault
 });
 ```
 
+When replacing only some repositories, also provide `prisma` for the remaining defaults. Custom repositories must share compatible transaction semantics. Optional capabilities such as idempotent persistence, bulk retry, replay, retention, and backlog reporting require the corresponding port methods; check the [consumer guide](./docs/usage.md) before replacing an adapter.
+
 ### Async configuration
 
+Supply the module that exports your `PrismaService` in `imports` so the factory can inject it:
+
 ```typescript
 WebhookModule.forRootAsync({
-  imports: [ConfigModule],
+  imports: [ConfigModule, PrismaModule],
   useFactory: (config: ConfigService, prisma: PrismaService) => ({
     prisma,
     delivery: {
-      maxRetries: config.get('WEBHOOK_MAX_RETRIES', 5),
+      maxRetries: Number(config.get('WEBHOOK_MAX_RETRIES') ?? 5),
     },
   }),
   inject: [ConfigService, PrismaService],
 });
 ```
 
-## Security
+`ConfigModule`/`ConfigService` are from `@nestjs/config`; `PrismaModule`/`PrismaService` are your application's providers.
 
-### Signing
+## Retries, replay, and delivery history
 
-All webhooks are signed with **HMAC-SHA256** using [Standard Webhooks](https://www.standardwebhooks.com/) headers:
+### Automatic retries and circuit breaking
 
-```
-webhook-id: <event-uuid>
-webhook-timestamp: <unix-seconds>
-webhook-signature: v1,<base64-hmac-sha256>
+The retry intervals are fixed at `30s`, `5m`, `30m`, `2h`, then `24h`; later retries repeat the `24h` interval. These are delays between attempts, before jitter. The default `maxRetries: 5` permits the initial request plus **four retries**, so it uses only the first four intervals. Set a total budget of at least `6` to reach the `24h` interval. The deprecated `delivery.backoff` option does not change this schedule.
+
+| Response | Behavior |
+|---|---|
+| `2xx` | Mark delivery `SENT` |
+| `3xx` | Retry while attempts remain; redirects are not followed |
+| `408`, `409`, `425`, `429` | Retry while attempts remain |
+| Other `4xx` | Mark delivery `FAILED` after the current attempt |
+| `5xx` | Retry while attempts remain |
+| Network, DNS, timeout, URL validation, or dispatch error | Retry while attempts remain |
+
+Failed attempts count toward the endpoint circuit breaker. Circuit breaking stops new publications from selecting an inactive endpoint and can restore it after cooldown. **Disabling an endpoint does not cancel deliveries already queued for it**; those rows remain eligible for processing, and a successful queued delivery can reactivate a circuit-disabled endpoint before cooldown. Manually disabled endpoints are excluded from automatic breaker recovery. Do not use endpoint disablement as queue cancellation.
+
+Notification callbacks are fire-and-forget; errors are logged and do not change persisted delivery state. `onDeliveryRetryScheduled` receives the next attempt time. `onDeliveryFailed` runs only for terminal failure, including a non-retryable response. Both carry failure details:
+
+| `failureKind` | Meaning | Additional fields |
+|---|---|---|
+| `url_validation` | URL rejected by SSRF validation | `validationReason`, `validationUrl`, `resolvedIp` when available |
+| `dispatch_error` | Connection, timeout, or other dispatch failure without an HTTP status; also unclassified dispatcher exceptions | — |
+| `http_error` | Non-success HTTP response | `responseStatus` |
+
+`onEndpointDegraded` fires at the exact configured failure count while the endpoint is active. `onEndpointDisabled` fires on the active-to-inactive transition. Callback `tenantId` is `null` for endpoints with no tenant.
+
+### Manual retry, bulk retry, and replay
+
+```typescript
+const retried = await deliveryAdmin.retryDelivery(deliveryId);
+
+const bulk = await deliveryAdmin.retryFailedDeliveries({
+  endpointId,
+  eventType: 'order.created',
+  limit: 100,
+});
+
+const replay = await deliveryAdmin.replayEvent(eventId, {
+  endpointIds: [endpointId],
+  tenantId: 'tenant_123',
+});
 ```
 
-**Secret format:** Secrets must be valid base64 strings decoding to at least 16 bytes. Use `"auto"` (case-sensitive) or omit `secret` for automatic generation.
+Manual retry requeues a failed delivery row, preserving its queued destination, secrets, and attempt count, and grants at least one additional attempt. It returns `false` if the delivery is not eligible. Bulk retry reports `matched`, `retried`, and `skipped`. From [0.13.2](./CHANGELOG.md#0132---2026-09-11), purged event payloads are ineligible for both paths.
 
-### SSRF defense
+Replay creates **new delivery rows** for the existing event ID using currently active matching endpoints and their current destination/secret snapshots. It preserves the source event's tenant scope; `tenantId` further restricts selection and cannot move an event into another tenant. A missing/purged event or an incompatible tenant filter throws; no matching endpoints returns `deliveriesCreated: 0`. Replay uses the configured `delivery.maxRetries` from [0.13.2](./CHANGELOG.md#0132---2026-09-11); `0.13.1` uses five attempts.
 
-- Endpoint URLs are validated at **registration** and at **every dispatch**
-- Blocks: private IPs, loopback, link-local, cloud metadata (169.254.x), IPv4-mapped IPv6
-- DNS resolution is checked to prevent rebinding attacks
-- HTTP redirects are disabled (`redirect: 'manual'`)
-- Use `allowPrivateUrls: true` for local development only
+Replay retains `webhook-id`, so a receiver that already processed that event may intentionally ignore it as a duplicate. Use a new business event if a separate processing operation is intended.
 
-**Structured validation errors** — validation failures throw `WebhookUrlValidationError` (subclass of `Error`) with a machine-readable `reason`:
+The public retry/replay options include `reason` for custom adapters. **The default Prisma adapter does not use or persist `reason`**; record support/audit notes in your application if needed.
 
-```ts
-import { WebhookUrlValidationError } from '@nestarc/webhook';
+### Delivery status and attempt history
 
-try {
-  await endpointAdmin.createEndpoint({ url, events: ['*'] });
-} catch (err) {
-  if (err instanceof WebhookUrlValidationError) {
-    // err.reason: 'parse' | 'scheme' | 'blocked_hostname'
-    //           | 'loopback' | 'private' | 'link_local' | 'invalid_target'
-    // err.url, err.resolvedIp also available
-    throw new BadRequestException({ message: err.message, reason: err.reason });
-  }
-  throw err;
+`getDeliveryLogs()` returns each delivery's current status and latest recorded result, including the snapshotted `destinationUrl`. `getDeliveryAttempts()` returns its recorded attempt history in ascending attempt order:
+
+```typescript
+const deliveries = await deliveryAdmin.getDeliveryLogs(endpointId, { limit: 20 });
+if (deliveries.length > 0) {
+  const attempts = await deliveryAdmin.getDeliveryAttempts(deliveries[0].id);
 }
 ```
 
-### Secret handling
+The default HTTP client retains at most **4096 UTF-16 code units** of response text. Attempt records have `responseBodyTruncated` for additional repository-side truncation; that flag does not detect text already truncated by the HTTP client. Redaction or retention can further remove response content. History records persisted worker observations, not every possible network outcome: a process crash after the request but before persistence can leave no recorded receiver response for that request. Use receiver-side logs when investigating that interval.
 
-- Signing secrets are excluded from read queries (`listEndpoints`, `getEndpoint`)
-- Secrets are only returned on `createEndpoint` (initial provisioning)
-- Delivery enrichment uses an internal path that does not expose secrets through admin APIs
-- **At-rest encryption** — provide a custom `WebhookSecretVault` to encrypt secrets before storage and decrypt before HMAC signing. The default `PlaintextSecretVault` passes values through unchanged.
-- **Rotation overlap** — use `rotateSecret()` to move the current stored secret to `previous_secret`, set a new current secret, and sign queued deliveries with both secrets until `previousSecretExpiresAt`.
+## Security and receiving webhooks
 
-```ts
-const rotated = await endpointAdmin.rotateSecret(endpointId, {
-  previousSecretExpiresAt: new Date(Date.now() + 24 * 60 * 60 * 1000),
-});
+### Signing and receiver verification
+
+Requests use HMAC-SHA256 over `<eventId>.<unixTimestamp>.<rawBody>` and these [Standard Webhooks](https://www.standardwebhooks.com/) headers:
 
-// Provision this value to the receiver immediately. It is returned only once.
-console.log(rotated?.secret);
+```text
+webhook-id: <event-uuid>
+webhook-timestamp: <unix-seconds>
+webhook-signature: v1,<base64-hmac-sha256>
 ```
 
-`WebhookSigner.verify()` accepts a request when any signature in the space-separated `webhook-signature` header matches the provided secret.
+Compatibility here refers to the **signature format and HTTP headers**, not every part of the Standard Webhooks specification. This package uses bare base64 secrets, without a `whsec_` prefix. `generateSecret()`, omitted secrets, and case-sensitive `"auto"` generate 32 random bytes; supplied secrets retain the legacy minimum of 16 decoded bytes.
 
-```ts
-const signer = new WebhookSigner();
-const isValid = signer.verify(
-  headers['webhook-id'],
-  Number(headers['webhook-timestamp']),
-  rawBody,
-  signingSecret,
-  headers['webhook-signature'],
-);
-```
+Verify the **original raw request body**, before parsing or reserializing JSON. Validate that the three headers are present as single strings, then verify signature and timestamp freshness:
 
-To reject replayed signatures, use an explicit timestamp tolerance:
+```typescript
+import { WebhookSigner } from '@nestarc/webhook';
 
-```ts
-const isValidFreshRequest = signer.verifyWithTolerance(
+const signer = new WebhookSigner();
+const valid = signer.verifyWithTolerance(
   headers['webhook-id'],
   Number(headers['webhook-timestamp']),
   rawBody,
@@ -566,78 +493,111 @@ const isValidFreshRequest = signer.verifyWithTolerance(
 );
 ```
 
-### Delivery audit data
+`verify()` checks only the signature. `verifyWithTolerance()` additionally rejects timestamps too far in the past **or future**. Neither method remembers previous requests: a repeated valid request within the tolerance window still passes. After verification, atomically deduplicate `webhook-id` with the receiver's business effects or durable enqueue operation, then return a `2xx` response. See the [executable receiver](./examples/quick-start/README.md) for the full flow.
 
-Delivery logs expose the snapshotted destination URL through `DeliveryRecord.destinationUrl`. Per-attempt audit records are available through `WebhookDeliveryAdminService.getDeliveryAttempts(deliveryId)`:
+### Secrets and rotation
 
-```ts
-const [delivery] = await deliveryAdmin.getDeliveryLogs(endpointId);
-const attempts = await deliveryAdmin.getDeliveryAttempts(delivery.id);
+- `createEndpoint()` and `rotateSecret()` return the new signing secret. `listEndpoints()` and `getEndpoint()` omit it.
+- The default `PlaintextSecretVault` stores secrets without encryption. Provide a `WebhookSecretVault` for encryption at rest; queue snapshots also contain signing material.
+- Normal delivery rows snapshot the endpoint URL and current secret when queued. Retries keep these values after endpoint changes.
+- Legacy rows created before `0.9.0` with null snapshots fall back to the endpoint's live URL/current key.
+
+```typescript
+const rotated = await endpointAdmin.rotateSecret(endpointId, {
+  previousSecretExpiresAt: new Date(Date.now() + 24 * 60 * 60 * 1000),
+});
+
+if (rotated) {
+  // Securely provision rotated.secret to the receiver.
+}
 ```
 
-## Webhook Payload Format
+The expiry is evaluated **when a delivery row is created**. Rows created before rotation retain the old secret; rows created during the overlap snapshot both secrets and can continue using both after `previousSecretExpiresAt`; rows created after expiry use only the current secret. Expiry does not revoke keys from existing queued rows. Coordinate receiver key retirement with queued deliveries and any planned manual retries. `verify()` and `verifyWithTolerance()` accept a match against any signature in the space-separated signature header for the supplied key.
 
-```json
-{
-  "type": "order.created",
-  "data": {
-    "orderId": "ord_123",
-    "total": 99.99
+### SSRF defense
+
+The default URL validator checks registration, URL updates, and every dispatch. It blocks private, loopback, link-local, metadata, and disallowed IPv4/IPv6 targets, resolves DNS, and the default HTTP client connects to the validated address. The default `FetchHttpClient` is implemented with Node.js `http.request`/`https.request`; it does not follow redirects. Custom HTTP clients must preserve these protections.
+
+Set `allowPrivateUrls: true` only for controlled local development or tests, such as the executable example's loopback receiver.
+
+URL validation failures expose structured errors:
+
+```typescript
+import { WebhookUrlValidationError } from '@nestarc/webhook';
+
+try {
+  await endpointAdmin.createEndpoint({ url, events: ['*'] });
+} catch (error) {
+  if (error instanceof WebhookUrlValidationError) {
+    // error.reason: parse | scheme | blocked_hostname | loopback
+    //             | private | link_local | invalid_target
+    // error.url and, when available, error.resolvedIp identify the target.
   }
+  throw error;
 }
 ```
 
-## Worker Separation
+## Worker separation
 
-By default the delivery worker runs inside your API process. For high-throughput scenarios, separate the worker into its own process so delivery HTTP calls don't compete with API request handling.
+By default, polling runs inside the NestJS application process. Run a separate worker process when delivery HTTP calls should have their own process capacity.
 
-**API process** — publishes events only:
+API process:
 
 ```typescript
-WebhookModule.forRoot({
-  prisma,
-  polling: { enabled: false },
-});
+WebhookModule.forRoot({ prisma, polling: { enabled: false } });
 ```
 
-**Worker process** — delivers webhooks only (no HTTP server):
+Worker process:
 
 ```typescript
-// worker.module.ts
+import { Module } from '@nestjs/common';
+import { NestFactory } from '@nestjs/core';
+import { WebhookModule } from '@nestarc/webhook';
+import { prisma } from './prisma';
+
 @Module({
-  imports: [
-    WebhookModule.forRoot({
-      prisma,
-      polling: { enabled: true, interval: 5000, batchSize: 50 },
-    }),
-  ],
+  imports: [WebhookModule.forRoot({ prisma })],
 })
-export class WorkerModule {}
+class WorkerModule {}
+
+async function main() {
+  const app = await NestFactory.createApplicationContext(WorkerModule);
+  const shutdown = async () => {
+    await app.close();
+    await prisma.$disconnect();
+  };
+  process.once('SIGTERM', () => void shutdown());
+  process.once('SIGINT', () => void shutdown());
+}
 
-// main.ts
-const app = await NestFactory.createApplicationContext(WorkerModule);
-process.on('SIGTERM', () => void app.close());
-process.on('SIGINT', () => void app.close());
+void main();
 ```
 
-Both processes share the same PostgreSQL database. Workers scale horizontally — `FOR UPDATE SKIP LOCKED` prevents duplicate delivery.
-During shutdown, the worker waits up to 30 seconds for the active poll cycle and in-flight deliveries. If the process exits earlier, the next worker recovers stuck `SENDING` rows after `polling.staleSendingMinutes`.
+API and worker processes must share the same PostgreSQL database and compatible configuration/vault. Multiple workers coordinate pending-row claims with `FOR UPDATE SKIP LOCKED`; the [duplicate-delivery limits](#publishing-and-delivery-guarantees) still apply.
+
+On application close, a worker waits up to 30 seconds for its active poll and in-flight deliveries. If shutdown interrupts a request, another worker can recover its stale `SENDING` row after `polling.staleSendingMinutes`. The application is responsible for invoking Nest shutdown and closing its Prisma client.
+
+## Using this package with an AI agent
+
+Start with the [package navigation index](./llms.txt), [consumer guide](./docs/usage.md), [executable quick start](./examples/quick-start/README.md), and installed `dist/index.d.ts`. Confirm the installed package version against the [changelog](./CHANGELOG.md) before using an API or an Unreleased fix. For hosted reference material, use the [package documentation](https://nestarc.dev/packages/webhook/), [API reference](https://nestarc.dev/api/webhook/), and site [llms.txt](https://nestarc.dev/llms.txt).
+
+Historical design and handover documents describe earlier implementations; use the consumer guide and current public types for application code. Treat tenant scope, raw-body verification, receiver deduplication, and finite retry budgets as part of the usage contract. An agent can validate integration by running the quick-start consumer against a disposable PostgreSQL database.
 
 ## Architecture
 
 ```mermaid
 flowchart LR
-  A[Your Service] -->|publish| B[WebhookService]
-  B -->|transactional insert| C[(PostgreSQL)]
-  D[DeliveryWorker] -->|poll and claim| C
+  A[Application service] -->|publish| B[WebhookService]
+  B -->|event and delivery transaction| C[(PostgreSQL)]
+  D[Delivery worker] -->|claim and record results| C
   D --> E[Dispatcher]
-  D --> F[RetryPolicy]
-  D --> G[CircuitBreaker]
-  E --> H[HttpClient]
-  H --> I[Customer endpoints]
+  D --> F[Retry policy]
+  D --> G[Circuit breaker]
+  E --> H[HTTP client]
+  H --> I[Webhook receivers]
 ```
 
-All components depend on **port interfaces**, not concrete implementations. Default adapters use Prisma and Node.js fetch.
+Components use port interfaces. Default persistence adapters use Prisma raw SQL; the default HTTP adapter uses Node.js `http`/`https`.
 
 ## License