About

Source: README.md

WebhookCore is a reusable webhook delivery and retry system for SaaS integrations.

It manages endpoints, signing, delivery attempts, retries, and replay without coupling the project to any specific product.

This repository is meant to be a reliable outbound integration foundation, not just a helper around fetch().

SaaS control plane

For repo routing, boundary guidance, release checks, and machine-readable catalog surfaces across the Saazip SaaS repos, use saasctl.

Why WebhookCore

WebhookCore exists for teams that need outbound webhooks to behave like a real delivery subsystem.

register and manage endpoints explicitly
sign payloads and verify signatures consistently
record delivery attempts as first-class state
retry failures with visible policy
support replay without inventing product-specific workflows
keep endpoint governance and auditability in one place

Typical use cases:

tenant event subscriptions
partner integrations
workflow notifications
outbound domain events

What WebhookCore is not

not an inbound webhook gateway
not a product-specific integration engine
not a hidden wrapper around QueueFlow

Quick start

cp .env.example .env
docker compose up -d postgres redis
pnpm install
pnpm dev:api
pnpm dev:dispatcher

Local services:

API: http://localhost:3030
Dispatcher: pnpm dev:dispatcher
Postgres: localhost:5434
Redis: localhost:6381

Operational defaults:

/health and /ready stay open for probes
/v1/* can be protected with API_KEYS
requests may send x-request-id, which is echoed back or generated
delivery attempts can be completed explicitly through POST /v1/deliveries/:id/attempts
delivery lists support cursor pagination plus tenantId, status, and failureReason filters

How to adopt WebhookCore

You can reuse WebhookCore in three ways:

1. Run it as a service

Use WebhookCore as a dedicated outbound delivery subsystem.

your product registers endpoints and creates deliveries through the API
WebhookCore owns retries, attempt logs, and replay behavior
useful when integrations need isolated operations and clear audit trails

2. Use the official SDK from this repository

Use the official client in packages/sdk to manage endpoints and dispatch deliveries from another service.

useful when your product already has a backend and you want a stable client layer
good for internal platforms that centralize delivery policy but not runtime ownership
npm publishing is intentionally deferred while the service API settles

3. Extend it in your product

Keep WebhookCore generic and decide in your product which domain events become outbound webhooks.

WebhookCore owns delivery mechanics
your product owns subscription semantics and event payload design
useful when you want reusable infrastructure without leaking product rules into the core

Repository map

apps/
  api/                Endpoint and delivery management API
  dispatcher/         Outbound dispatcher runtime
packages/
  core/               Delivery model, retry policy, and topic helpers
  contracts/          Public HTTP contracts
  crypto/             Signing and verification helpers
  db/                 Drizzle schema and persistence helpers
  sdk/                Official SDK workspace kept private in this phase
  adapters/queueflow/ Official retry orchestration adapter
  testing/            Fixtures for downstream adopters
docs/                 Architecture, concepts, operations, ADRs
examples/             Reference integration examples
docker/               Local infrastructure config

For contributors

If you want to contribute, start here:

Read this README for product boundaries.
Read docs/README.md for the docs map.
Read CONTRIBUTING.md before changing delivery semantics or signature behavior.

Useful commands:

pnpm run ci
pnpm dev:api
pnpm dev:dispatcher
pnpm example:outbound-integration

Contribution areas that add value early:

retry and failure classification hardening
secret rotation and provider boundaries
delivery observability and metrics
docs, examples, and operational guidance

Project docs

Distribution note

WebhookCore is service-first in v1.

the HTTP API is the primary adoption surface
packages/sdk is the official client kept inside this repository for now
public npm publishing is intentionally deferred until the service contract is more stable

Compatibility

Node 24.x
pnpm 10.33.x
PostgreSQL 16+
Redis 7+
QueueFlow adapter optional

@saazip/queueflow can orchestrate delivery retries through an adapter
@saazip/eventflow can emit events that feed outbound deliveries
@saazip/cache-core can cache endpoint and subscription lookups

License

Apache-2.0