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

2.0 KiB Raw Blame History