@suaveplan/webhook-client - Webhook delivery client with retry logic, HMAC signature generation/verification, payload transformation, and delivery tracking

Summary

Webhook delivery client with retry logic, HMAC signature generation/verification, payload transformation, and delivery tracking. Runtime-agnostic (injectable fetch).

Documentation tree

client — (no submodules)
- webhook-client — (no submodules)
delivery — (no submodules)
- webhook-delivery — (no submodules)
errors — (no submodules)
- webhook-client-error — (no submodules)
payload-builder — Provides utilities for constructing and serializing WebhookPayload objects before delivery. The two functions in this…
signature — Provides HMAC signature generation and verification for webhook payloads using the Web Crypto API (`globalThis.crypto.s…

- [webhook-client](./src/core/client/webhook-client.md) — _(no submodules)_- [delivery](./src/core/delivery/webhook-delivery.md) — _(no submodules)_- [webhook-delivery](./src/core/delivery/webhook-delivery.md) — _(no submodules)_- [errors](./src/errors/webhook-client-error.md) — _(no submodules)_- [webhook-client-error](./src/errors/webhook-client-error.md) — _(no submodules)_- [payload-builder](./src/utils/payload-builder.md) — Provides utilities for constructing and serializing `WebhookPayload` objects before delivery. The two functions in this…

signature — Provides HMAC signature generation and verification for webhook payloads using the Web Crypto API (`globalThis.crypto.s…
webhook-client — (no submodules)- delivery — (no submodules)- webhook-delivery — (no submodules)- errors — (no submodules)- webhook-client-error — (no submodules)- payload-builder — Provides utilities for constructing and serializing WebhookPayload objects before delivery. The two functions in this…
signature — Provides HMAC signature generation and verification for webhook payloads using the Web Crypto API (`globalThis.crypto.s…
webhook-client — (no submodules)- delivery — (no submodules)- webhook-delivery — (no submodules)- errors — (no submodules)- webhook-client-error — (no submodules)- payload-builder — Provides utilities for constructing and serializing WebhookPayload objects before delivery. The two functions in this…
signature — Provides HMAC signature generation and verification for webhook payloads using the Web Crypto API (`globalThis.crypto.s…
webhook-client — (no submodules)- delivery — (no submodules) - webhook-delivery — (no submodules)- errors — (no submodules) - webhook-client-error — (no submodules)- payload-builder — Provides utilities for constructing and serializing WebhookPayload objects before delivery. The two functions in this…
signature — Provides HMAC signature generation and verification for webhook payloads using the Web Crypto API (`globalThis.crypto.s…

Installation

bun add @suaveplan/webhook-client

Quick Start

import { createWebhookClient } from '@suaveplan/webhook-client';

const client = createWebhookClient({
  url: 'https://partner.example.com/webhooks',
  secret: 'shared-secret',
  maxRetries: 3,
  retryDelay: 1000,
});

const result = await client.send('order.created', { orderId: 42 });
console.log(result.status); // 'delivered'

Modules

Module	Path	Description
Client	src/core/client/webhook-client.md	`WebhookClient` class and `createWebhookClient` factory
Delivery	src/core/delivery/webhook-delivery.md	Core HTTP delivery engine with retry logic
Signature	src/utils/signature.md	HMAC signature generation and verification
Payload Builder	src/utils/payload-builder.md	Payload construction and deterministic serialization
Errors	src/errors/webhook-client-error.md	Error codes and `WebhookClientError` class

Subpath Exports

import { createWebhookClient } from '@suaveplan/webhook-client';
import { deliver } from '@suaveplan/webhook-client/delivery';
import { generateSignature, verifySignature } from '@suaveplan/webhook-client/signature';
import { WEBHOOK_CLIENT_CODES, WebhookClientError } from '@suaveplan/webhook-client/errors';

Configuration

interface WebhookConfig {
  url: string;
  secret?: string;                     // HMAC secret
  algorithm?: 'sha256' | 'sha512';     // default: 'sha256'
  headers?: Record<string, string>;    // additional headers
  timeout?: number;                    // ms, default: 30000
  maxRetries?: number;                 // default: 3
  retryDelay?: number;                 // base delay ms, default: 1000
}

Retry Behaviour

Delivery uses exponential backoff with full jitter via @suaveplan/retry:

2xx → success, no retry
429 / 5xx → transient, retried up to maxRetries
4xx (except 429) → terminal, not retried

HMAC Signatures

When secret is configured, every delivery attaches:

X-Hub-Signature-256: sha256=<hex> (default)
X-Hub-Signature-512: sha512=<hex> (when algorithm: 'sha512')

Verification uses Web Crypto API constant-time comparison.

OTel Metrics

Metric	Type	Labels
`webhook_client.delivery.total`	Counter	`event`, `status`
`webhook_client.delivery.duration_ms`	Histogram	`event`, `status`