Initial Commit

openspec/archive/2026-04-19-enterprise-webhook-client/proposal.md

@@ -0,0 +1,56 @@
+# OpenSpec Change: enterprise-webhook-client
+
+- **Change ID**: enterprise-webhook-client
+- **Package**: `@suaveplan/webhook-client`
+- **Category**: universal
+- **Target path**: `universal/messaging/webhook-client`
+- **Status**: PROPOSED
+- **Date**: 2026-04-19
+- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/webhook-client.md`
+
+## Summary
+
+Greenfield rebuild of `@suaveplan/webhook-client` — outgoing webhook receiver with signature verification, configurable parser and schema registry, HMAC / JWS signature schemes, listener API, and a hook surface for pre/post delivery observability. Signs outgoing requests with `@suaveplan/crypto`.
+
+## Current-state audit (genesis)
+
+Package does not exist yet — fresh build.
+
+## Dependencies
+
+- Workspace: `@suaveplan/error`, `@suaveplan/events`, `@suaveplan/types`, `@suaveplan/crypto`
+- External (via catalog): `zod`, `tslib`, `@opentelemetry/api`
+- Dev (via catalog): `vitest`, `@vitest/coverage-istanbul`, `fast-check`, `mitata`
+
+## Preserved public surface
+
+### Receiver / parser / verifier
+
+- `WebhookReceiver`, `ReceiverErrorCode`, `WebhookListener`
+- `WebhookParser`, `ParserErrorCode`
+- `WebhookVerifier`, `VerifierErrorCode`
+
+### Hooks
+
+- `onWebhookDelivering`, `webhookHooks`, `WebhookDeliveringHookData`, `WebhookHookMap`
+
+### Error codes
+
+- `WebhookErrorCode`, `WEBHOOK_ERROR_METADATA`, `registerWebhookErrorCodes`
+
+### Types
+
+`ParsedWebhookEvent`, `SignatureScheme`, `VerificationResult`, `WebhookConfig`, `WebhookPayload`, `WebhookSchema`.
+
+## New genesis additions
+
+- Codes: `WEBHOOK.INVALID_SIGNATURE`, `WEBHOOK.REPLAY_DETECTED`, `WEBHOOK.SCHEMA_MISMATCH`, `WEBHOOK.LISTENER_ERROR`.
+- Zod schemas for every type.
+- Timestamp-based replay protection (`WebhookConfig.maxSkewSeconds`).
+- OTel histograms `webhook.receive.duration_ms`, `webhook.verify.duration_ms`; counters for outcome.
+- Property tests: HMAC sign/verify round-trip; replay rejection above skew.
+
+## Impact
+
+- Adds one new package: `universal/messaging/webhook-client`
+- Adds one new spec capability: `webhook-client`