WebhookCore

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:

1. Read this README for product boundaries.
2. Read docs/README.md for the docs map.
3. 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

• Contributing guide
• Security policy
• Architecture and concepts
• API reference
• Compose with the Saazip infra suite
• Release checklist
• Outbound integration example

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

Related projects

• @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