# 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`