57 lines
2.0 KiB
Markdown
57 lines
2.0 KiB
Markdown
# 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`
|