OpenSpec Change: enterprise-api-plugin-webhook

Change ID: enterprise-api-plugin-webhook
Package: @suaveplan/api-plugin-webhook
Category: api/comms
Target path: api/comms/api-plugin-webhook
Status: PROPOSED
Date: 2026-04-24
Reference spec: /mnt/s/web/suaveplan/enterprise/api-plugin-webhook.md

Summary

Deliver @suaveplan/api-plugin-webhook on the genesis branch from scratch at enterprise quality. Outbound webhook management plugin: endpoint CRUD (URL + secret + subscribed event types), delivery engine via @suaveplan/webhook-client (HMAC-SHA256 signing + retry), delivery log, manual replay, pause/resume per endpoint, and fan-out subscriptions. Routes under /webhooks. Per-table SurrealQL. Typed bus events: webhook:delivered, webhook:failed, webhook:endpoint:created.

Available workspace deps on genesis

Package	Role
`@suaveplan/api` (`workspace:^`)	`definePlugin`
`@suaveplan/api-shared` (`workspace:^`)	Helpers
`@suaveplan/api-plugin-auth` (`workspace:^`)	`requireAuth`
`@suaveplan/api-plugin-database` (`workspace:^`)	SurrealDB
`@suaveplan/webhook-client` (`workspace:^`)	HMAC signing + delivery
`@suaveplan/events` (`workspace:^`)	Bus subscriptions
`@suaveplan/error` (`workspace:^`)	`WebhookPluginError` hierarchy
`@suaveplan/audit-logging` (`workspace:^`)	Delivery audit
`@suaveplan/rate-limiter` (`workspace:^`)	Rate limits
`hono` + `@hono/zod-openapi` + `zod`	Routes
`@opentelemetry/api`	OTel

Public API surface

function createWebhookPlugin(config?: WebhookPluginConfig): PluginDescriptor
// Services: EndpointService, DeliveryService
// Routes: /webhooks/endpoints, /webhooks/endpoints/:id,
//         /webhooks/endpoints/:id/deliveries, /webhooks/endpoints/:id/replay/:deliveryId,
//         /webhooks/endpoints/:id/pause, /webhooks/endpoints/:id/resume

Error codes

type WebhookPluginErrorCode =
  | "WEBHOOK_ENDPOINT_NOT_FOUND"
  | "WEBHOOK_DELIVERY_NOT_FOUND"
  | "WEBHOOK_ENDPOINT_PAUSED"
  | "WEBHOOK_INVALID_URL"
  | "WEBHOOK_DELIVERY_FAILED"

File layout

api/comms/api-plugin-webhook/
  package.json  tsconfig.json  vitest.config.ts
  surql/ (webhook_endpoint, webhook_delivery tables)
  src/
    index.ts  events.ts  types/  errors/
    services/endpoint/  services/delivery/
    routes/webhooks/
  tests/integration.test.ts

Impact

Prerequisites: @suaveplan/api, @suaveplan/api-plugin-auth, @suaveplan/api-plugin-database, @suaveplan/webhook-client, @suaveplan/events, @suaveplan/audit-logging.

2.6 KiB Raw Permalink Blame History