suaveplan/openspec/archive/2026-05-18-add-api-plugin-webhook/proposal.md

Add @suaveplan/api-plugin-webhook — Signed outbound webhook delivery as a definePlugin

Package: @suaveplan/api-plugin-webhook (NEW, server-tier) Status: PROPOSED Type: new-package Position: server plugin layered on @suaveplan/api + @suaveplan/webhook-client; depends only on already-shipped foundations (api-plugin, api-openapi, webhook-client, idempotency, types, error)

• Spec delta: ./specs/api-plugin-webhook/spec.md

Why

Genesis ships @suaveplan/webhook-client (HMAC-signed delivery + retry, 0.1.0) and the @suaveplan/api-plugin / @suaveplan/api-openapi foundation. Every API that needs to fan signed events out to subscriber endpoints (order events, account events, partner notifications) currently has to wire endpoint storage, route validation, retry queue orchestration, dead-letter sink, and signature header conventions by hand. That defeats the point of having a webhook client and an OpenAPI plugin foundation.

This package collapses that scaffolding into a single createWebhookPlugin(options) factory that:

1. Registers a typed webhookService in the host ServiceRegistry exposing send(endpoint, event) / register(endpoint) / unregister(id) / listEndpoints(tenantId?).
2. Mounts a small CRUD surface for subscription management (GET/POST /webhooks, GET/PATCH/DELETE /webhooks/:id, plus POST /webhooks/:id/test) gated by requireAuth() and tenant-scoped if the request carries a tenant.
3. Drives delivery through @suaveplan/webhook-client (HMAC-SHA256 by default, exponential backoff with jitter, 5 attempt cap, dead-letter sink) and uses @suaveplan/idempotency for per-delivery dedup so callers can safely retry send().
4. Persists endpoints behind an EndpointStore interface with an in-memory default — a SurrealDB-backed sibling plugin lands separately.

It is the canonical exemplar of "wrap a @suaveplan/<lib> library as a @suaveplan/api-plugin-*" for downstream plugins that follow the same shape (api-plugin-rate-limit, api-plugin-audit).

What changes

Net-new package at 0.1.0. ADDED:

Plugin factory + descriptor

• createWebhookPlugin(options: WebhookPluginOptions): PluginDescriptor<WebhookPluginConfig> — Zod-validated factory returning a PluginDescriptor from @suaveplan/api-plugin. Invalid input raises WebhookError(WEBHOOK_INVALID_INPUT) carrying the ZodError as cause.
• WebhookPluginOptions (validated via WebhookPluginOptionsSchema): { routePrefix?: string (default "/webhooks"); endpointStore?: EndpointStore; deadLetterSink?: DeadLetterSink; maxAttempts?: number (default 5); initialRetryDelayMs?: number (default 500); maxRetryDelayMs?: number (default 30_000); idempotencyGuard?: DistributedIdempotencyGuard; logger?: LoggerLike; clock?: Clock; fetch?: FetchLike }. Every optional dep that isn't supplied defaults to an injectable in-memory implementation owned by the package.
• WebhookPluginConfig — the resolved (post-default-merge) options shape.

Endpoint store contract (the persistence seam)

• EndpointStore interface: list({ tenantId? }): Promise<readonly WebhookEndpoint[]> / get(id): Promise<WebhookEndpoint | null> / create(input: CreateEndpointInput): Promise<WebhookEndpoint> / update(id, patch: UpdateEndpointInput): Promise<WebhookEndpoint> / delete(id): Promise<void>.
• MemoryEndpointStore — default in-memory Map-backed implementation. Thread-safe under cooperative async (no concurrent JS execution).
• WebhookEndpoint: { id: string; tenantId: string | null; url: string; secret: string; events: readonly string[]; description?: string; headers?: Record<string, string>; algorithm: "sha256" | "sha512"; active: boolean; createdAt: string; updatedAt: string }.
• WebhookEndpointSchema / CreateEndpointInputSchema / UpdateEndpointInputSchema Zod schemas — used at the route boundary and by the store conformance harness.

Dead-letter sink

• DeadLetterSink interface: record(entry: DeadLetterEntry): Promise<void> / list({ endpointId?, limit? }): Promise<readonly DeadLetterEntry[]>.
• MemoryDeadLetterSink — default in-memory implementation. Records every delivery that exhausts maxAttempts retries with the full DeliveryResult.attempts history, the originating event, and the firstAttemptAt / finalAttemptAt timestamps.
• DeadLetterEntry: { id: string; endpointId: string; tenantId: string | null; event: string; payload: WebhookPayload; attempts: readonly DeliveryAttempt[]; firstAttemptAt: string; finalAttemptAt: string; reason: string }.

Webhook service (registered in the host ServiceRegistry)

• WebhookService interface: send(endpointId, event, data): Promise<DeliveryResult> / sendAll(event, data, { tenantId? }): Promise<readonly DeliveryResult[]> (fans out to every active endpoint subscribed to event) / register(input): Promise<WebhookEndpoint> / unregister(id): Promise<void> / listEndpoints(filter): Promise<readonly WebhookEndpoint[]> / test(endpointId): Promise<DeliveryResult> (sends a synthetic webhook.ping payload).
• ServiceRegistry module augmentation: declare module "@suaveplan/api-plugin/service-registry" { interface ServiceRegistry { webhookService: WebhookService } }.

Routes (the OpenAPI surface)

All routes mount at options.routePrefix (default /webhooks), are gated by requireAuth(), and filter by tenant when the request principal carries a tenantId:

• GET /webhooks — list active endpoints for the current tenant (admin sees all).
• POST /webhooks — create an endpoint. Body: CreateEndpointInputSchema. Caller supplies the HMAC secret.
• GET /webhooks/:id — read one endpoint. Returns 404 on miss or tenant mismatch.
• PATCH /webhooks/:id — partial update (url, events, headers, active flag, description). Cannot rotate tenantId. Secret rotation is opt-in via the body.
• DELETE /webhooks/:id — hard delete. Idempotent on miss.
• POST /webhooks/:id/test — fire a synthetic webhook.ping event at the endpoint and return the DeliveryResult. Honours rate limit + idempotency.

Every route is built with RouteBuilder (POST/GET/PATCH/DELETE from @suaveplan/api-openapi) so the unified /openapi.json includes Zod-typed request/response shapes for every method.

Delivery semantics

• Signing — HMAC-SHA256 by default via generateSignature from @suaveplan/webhook-client/signature. Algorithm pinned per endpoint. Header naming follows webhook-client convention (X-Hub-Signature-256 / X-Hub-Signature-512).
• Standard outbound headers — X-Webhook-Id (delivery id), X-Webhook-Event (event name), X-Webhook-Timestamp (ISO 8601 UTC), plus signature header above. Caller-supplied endpoint.headers are merged with these (caller wins on Content-Type only, never on the four canonical headers).
• Retry — exponential backoff with full jitter, starting at initialRetryDelayMs, doubling each attempt, capped at maxRetryDelayMs, exhausted after maxAttempts (default 5). Receivers returning 4xx (except 429) terminate immediately; 429 and 5xx retry; network errors and timeouts retry.
• Dead-letter — once maxAttempts is exhausted, the package records a DeadLetterEntry via the configured sink and surfaces a WebhookError(WEBHOOK_DELIVERY_EXHAUSTED) to the caller of send(). The entry preserves the full attempt history so operators can replay manually.
• Idempotency — every send() call computes a delivery key from (endpointId, payload.id). When an idempotencyGuard is supplied, the call routes through guard.execute(key, () => delivery) so duplicate sends within the dedup window return the cached result. Without a guard, deliveries are dedup'd per process via an in-flight Map.

Errors + observability

• WebhookError extends SuaveplanError<WebhookErrorCode> via defineCodes("WEBHOOK", [...]). Codes: INVALID_INPUT, ENDPOINT_NOT_FOUND, TENANT_MISMATCH, EVENT_NOT_SUBSCRIBED, DELIVERY_EXHAUSTED, DEAD_LETTER_WRITE_FAILED, STORE_ERROR, SERVICE_NOT_AVAILABLE, ROUTE_PREFIX_COLLISION, INACTIVE_ENDPOINT.
• OTel: counters webhook_plugin.deliveries_total{event,status,endpoint_id}, webhook_plugin.dead_letters_total{event,endpoint_id}; histogram webhook_plugin.delivery_attempts{event,status}; histogram webhook_plugin.send_duration_ms{status}. Registered via the package's own getWebhookInstruments() factory pattern (mirrors api-plugin-auth).

Subpath exports

., ./plugin/plugin, ./services/webhook-service, ./store/endpoint-store, ./store/memory-store, ./dead-letter/dead-letter, ./dead-letter/memory-sink, ./routes/routes, ./schemas/options, ./schemas/endpoint, ./schemas/routes, ./error-codes/error-codes, ./otel/instruments, ./types/types.

Out of scope

• SurrealDB-backed endpoint store. Lands as a sibling @suaveplan/api-plugin-webhook-surreal plugin — keeps this package zero-IO so it can land in any storage tier.
• Inbound webhook receivers. This package is delivery-only; consuming webhooks from third parties belongs to a future @suaveplan/api-plugin-webhook-receiver.
• Replay UI / admin dashboard. Dead-letter entries are exposed via the DeadLetterSink interface; surfacing them in an admin app is per-application.
• Cron-based redelivery from the dead-letter sink. The sink records entries; redelivery orchestration lives in the operator's scheduled jobs.
• Multi-tenant tenant-id auto-injection. Tenants are owned by @suaveplan/api-tenant; this plugin reads c.get("user")?.tenantId if the auth plugin is wired upstream and falls back to global scope otherwise.
• Filter / transform DSL. Endpoints subscribe to literal event names today. A glob / topic DSL is deferred until two consumers need it.

Source mapping

This package is genesis-original — there is no upstream packages/server/api-plugin-webhook/ in ../suaveplan/ to port (only the enterprise audit doc ../suaveplan/enterprise/api-plugin-webhook.md, which describes intent but not implementation). Design intent is drawn from:

• ../suaveplan/enterprise/api-plugin-webhook.md — the enterprise audit (118 lines) that scopes purpose, required improvements, and acceptance criteria.
• Genesis @suaveplan/api-plugin PluginContext + ServiceRegistry shape (commit 0f338653).
• Genesis @suaveplan/api-openapi definePluginRoutes + RouteBuilder (commit 99a213ed).
• Genesis @suaveplan/webhook-client (HMAC signing, retry, attempt tracking).
• Genesis @suaveplan/api-plugin-auth (canonical definePlugin consumer shape — service registration, route mounting, ServiceRegistry augmentation, OTel pattern, error-code shape).
• Genesis @suaveplan/idempotency DistributedIdempotencyGuard.

Requirement	Source	Notes
Plugin wiring via definePlugin	enterprise/api-plugin-webhook.md L37 + @suaveplan/api-plugin	"Plugin wiring — built with definePlugin() from @suaveplan/api, full onInit/onReady/onClose lifecycle"
Zod request/response schemas at route boundary	enterprise/api-plugin-webhook.md L39	"Zod request/response schemas via @suaveplan/api-schemas — published OpenAPI 3.1 + JSON Schema"
Auth gating + tenant isolation	enterprise/api-plugin-webhook.md L40	"Authentication & authorization — JWT, RBAC, tenant isolation enforced in every query" — adapted to genesis requireAuth()
Idempotency on mutations	enterprise/api-plugin-webhook.md L42	"Idempotency — Idempotency-Key header, @suaveplan/idempotency guard on all mutations"
Observability — counters / histograms / spans	enterprise/api-plugin-webhook.md L44	"OpenTelemetry spans, @suaveplan/logger structured logs with trace correlation, Prometheus metrics"
Retries + dead-letter sink on external calls	enterprise/api-plugin-webhook.md L45	"Retries & circuit breakers on external calls via @suaveplan/retry" — extended with dead-letter sink
HMAC-signed delivery	enterprise/api-plugin-webhook.md L47	"Webhooks — signed via @suaveplan/webhook-client, delivery tracked via @suaveplan/delivery-tracking"
No mocks — real services in tests	enterprise/api-plugin-webhook.md L48 + L55	"Integration tests against real services (no mocks)" — genesis enforces via real Hono receiver
100% coverage / docs / no banned patterns	enterprise/api-plugin-webhook.md L52-L65	"Cross-cutting (every package)" block
File-size + biome + no any budget	enterprise/api-plugin-webhook.md L54 + L60-L61	inherited from CLAUDE.md

Requirements with no source line

Requirement	Justification
Pluggable EndpointStore interface	Decouples persistence so SurrealDB / Redis / Postgres siblings can plug in without forking. The audit calls for SurrealDB integration but explicitly invites pluggable stores via L37 "Plugin / extension interface (where it makes sense) so downstream packages can contribute behaviour without forking" (L71).
Pluggable DeadLetterSink interface	Same rationale — operators may wire dead letters into Mailpit / Slack / S3.
Per-delivery in-flight dedup without an external guard	Default safety net so callers don't have to wire @suaveplan/idempotency to get re-entrancy safety. Audit L42 calls for the guard on mutations; this extends the safety net to single-process delivery.

Verification approach

Every requirement in specs/api-plugin-webhook/spec.md carries a **Verified by:** line pointing at:

• src/<feature>/<feature>.test.ts — unit scenarios (no IO, injectable defaults).
• src/<feature>/<feature>.spec-conformance.test.ts — type-level + observability + lifecycle scenarios.
• tests/integration/delivery.test.ts — real listening Hono receiver on a random port; verifies signed payload, headers, retry-then-success, dead-letter after 5x 500.
• tests/integration/full-boot.test.ts — real PluginRegistry + real Hono app; full register → send → receive → assert round-trip.
• tests/dep-graph.test.ts — pins dependency invariants (14 subpaths, sibling .md per impl file).

Migration impact

None — additive, net-new package. No existing consumer in the monorepo (bunx turbo ls --filter=...@suaveplan/api-plugin-webhook returns empty).

Impact

Affected dependents

No dependents (verified by bunx turbo ls --filter=...@suaveplan/api-plugin-webhook returning the empty set on the genesis branch — net-new package).

Catalog additions required

None. All deps are already pinned: hono (catalog:server), @hono/zod-openapi (catalog:server), zod (catalog:forms), @opentelemetry/api (catalog:observability).