Initial Commit

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

@@ -0,0 +1,33 @@
+# Capability Spec: webhook-client
+
+**Package**: `@suaveplan/webhook-client`
+**Version**: 0.0.0 (genesis)
+**Status**: ADDED
+
+---
+
+## ADDED Requirements
+
+### WH-01 — Signature schemes
+
+`SignatureScheme` MUST include `'hmac-sha256'` and `'jws'`. `WebhookVerifier.verify(request, config)` MUST compute the signature per scheme and compare in constant time. Mismatches MUST throw `WEBHOOK.INVALID_SIGNATURE`.
+
+### WH-02 — Replay protection
+
+`WebhookConfig.maxSkewSeconds` (default 300) MUST bound the accepted timestamp delta. Requests outside the skew MUST throw `WEBHOOK.REPLAY_DETECTED`. The verifier MUST include the timestamp in the signing-string.
+
+### WH-03 — Parse contract
+
+`WebhookParser.parse(request)` MUST accept `application/json`, `application/x-www-form-urlencoded`, and `text/plain`. Payloads MUST be Zod-validated against the configured `WebhookSchema`. Validation failures MUST throw `WEBHOOK.SCHEMA_MISMATCH`.
+
+### WH-04 — Receiver
+
+`WebhookReceiver.handle(request)` MUST run verify → parse → dispatch-listeners. Listener exceptions MUST be captured per-listener, emit `WEBHOOK.LISTENER_ERROR` with context, and continue with the remaining listeners.
+
+### WH-05 — Hooks
+
+`webhookHooks.delivering` MUST fire with `WebhookDeliveringHookData { event, listener, startedAt }` before each listener invocation. Handlers MUST be able to veto delivery by throwing.
+
+### WH-06 — Observability
+
+Every `handle` call MUST record `webhook.receive.duration_ms`; every verify MUST record `webhook.verify.duration_ms`; outcome counters MUST label `scheme` and `result`.