34 lines
1.5 KiB
Markdown
34 lines
1.5 KiB
Markdown
# 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`.
|