Good Webhooks

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.

You want	Start with
Everything on PostgreSQL	Quick start
To see what a hand-rolled sender gets wrong	Tutorial
Signed-in users managing their own endpoints	Better Auth plugin
Better Auth endpoints with built-in delivery	Add delivery
Endpoint management for your own sender	Custom senders
Only receiving webhooks	Receive webhooks
To compare with Svix, Outpost, Convoy, or pg-boss	Compared with alternatives

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.