1.5 KiB
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.