You publish typed events. Good Webhooks stores them in your PostgreSQL database, and a worker you run delivers signed Standard Webhooks requests, retries failures, and records every attempt. Receivers verify a request with one function. Endpoint management works standalone, through the Better Auth plugin, or with your own sender.
Stable API. From 0.1.0 the public API and upgrade path follow the stability policy. Throughput beyond the measured profile is not yet verified.
Install
npm install good-webhooks pg zod
Requires Node.js 24 or later. Built-in delivery and standalone management need PostgreSQL 16, 17, or 18. Better Auth management uses your existing Better Auth database adapter. See installation for each setup's dependencies and the compatibility policy for tested versions.
The package README walks through publishing, running a worker, and verifying on the receiving side.
Try the Playground
playground.good-webhooks.dev is a public app built on the published package. Sign in with GitHub, add an HTTPS endpoint, and receive signed events within minutes. Its source is a complete deployment and the library's dogfood.
Run complete applications
Two interactive examples show the full path from a business action to a verified webhook and receiver outcome:
- Order fulfillment: place a shop order, send it to a warehouse, simulate an outage, and replay a delivery without creating a second shipment.
- Better Auth billing: sign in, manage personal endpoints, publish invoice events, and inspect delivery attempts within the signed-in user's scope.
Each example has its own npm lockfile, PostgreSQL setup, browser UI, receiver, and separate worker process. Both install [email protected] from npm and can run together. Follow the examples guide to get started.
Work on the repository
| Directory | Contents |
|---|
packages/good-webhooks | Public package source, examples, migrations, and tests |
apps/docs | Fumadocs site behind good-webhooks.dev |
examples | Complete applications that install the published npm package |
docs | Engineering plans and architecture decisions |
Use Node.js 24 and the repository's pinned pnpm version, 12.10.1. If Corepack is available, enable its shims with corepack enable; otherwise install that pnpm version using the pnpm installation instructions.
pnpm install --frozen-lockfile
pnpm dev
Open http://localhost:3000 for the documentation site. To build, check links, and run the production build:
pnpm build
pnpm --filter @good-webhooks/docs check:links
pnpm --filter @good-webhooks/docs preview
Run pnpm check, pnpm format:check, and pnpm test:unit for checks without a PostgreSQL server. The contribution guide covers integration tests, adapter checks, and documentation verification.
Try the example
The standalone demo demonstrates rollback, signed delivery, retry, replay, and durable receiver deduplication. Start a disposable database:
docker run --name good-webhooks-demo \
-e POSTGRES_PASSWORD=webhooks_dev_only \
-e POSTGRES_DB=webhooks \
-p 127.0.0.1:55439:5432 \
-d postgres:16
Wait until PostgreSQL accepts connections, then apply the migrations once:
export DATABASE_URL='postgres://postgres:[email protected]:55439/webhooks'
psql "$DATABASE_URL" --single-transaction -v ON_ERROR_STOP=1 -f packages/good-webhooks/migrations/001-initial.sql
psql "$DATABASE_URL" --single-transaction -v ON_ERROR_STOP=1 -f packages/good-webhooks/examples/basic/receiver.sql
pnpm example
The demo leaves event, attempt, and receiver history for inspection. Do not run the integration tests against this database; those tests reset their database tables.
Install a local archive
pnpm --dir packages/good-webhooks pack
In your application, install the resulting archive using npm or your preferred package manager:
npm install /absolute/path/to/packages/good-webhooks/good-webhooks-0.6.0.tgz
pnpm test:package verifies the archive with fresh npm consumers, both with and without Better Auth, including the published declarations and SQL exports. Registry publication is a separate release step.
Contributing
Read CONTRIBUTING.md before proposing changes. Maintainers use the release guide to verify a candidate before publishing. Report vulnerabilities through the security policy. Licensed under MIT.
