78 lines
2.6 KiB
Markdown
78 lines
2.6 KiB
Markdown
# 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
|
|
|
|
```ts
|
|
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
|
|
|
|
```ts
|
|
type WebhookPluginErrorCode =
|
|
| "WEBHOOK_ENDPOINT_NOT_FOUND"
|
|
| "WEBHOOK_DELIVERY_NOT_FOUND"
|
|
| "WEBHOOK_ENDPOINT_PAUSED"
|
|
| "WEBHOOK_INVALID_URL"
|
|
| "WEBHOOK_DELIVERY_FAILED"
|
|
```
|
|
|
|
---
|
|
|
|
## File layout
|
|
|
|
```text
|
|
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`.
|