# Good Webhooks

> Good Webhooks is a TypeScript library for sending webhooks from a Node.js application. You publish typed events; it stores them in your PostgreSQL database, delivers signed Standard Webhooks requests from a worker you run, retries failures, keeps attempt history, and supports replay. Receivers verify requests with one function. Endpoints are managed through a standalone PostgreSQL provider or a Better Auth plugin.

Version 0.1.0-beta.3 (beta: pin the exact version). Requires Node.js 24 or later and PostgreSQL 16 or 17. Better Auth >=1.7.7 <1.8.0 is optional.

**When to use it:** your application sends webhooks to customers and you want delivery to live in your own process and database, with no hosted service.

**When not to use it:** edge runtimes, delivery storage other than PostgreSQL, or a fully hosted webhook service.

**How to use these docs:** every link below is a Markdown page. For a runnable start, read the quick start. For an existing app, read installation, publish events, run workers, and receive webhooks, then the production checklist. All pages in one file: https://good-webhooks.dev/llms-full.txt

## Get started

- [Introduction](https://good-webhooks.dev/docs.md): Good Webhooks is a TypeScript library that adds outbound webhooks to your application, using your PostgreSQL database.
- [Installation](https://good-webhooks.dev/docs/installation.md): Add Good Webhooks to an existing application. Install, create a key and the tables, and connect.
- [Quick start](https://good-webhooks.dev/docs/quick-start.md): Send your first signed webhook in about five minutes. One database, one file, one command.
- [Examples](https://good-webhooks.dev/docs/examples.md): Two complete applications that install the published package and show the full path from a business action to a verified webhook.

## Concepts

- [How it works](https://good-webhooks.dev/docs/concepts/how-it-works.md): Endpoint management decides who receives events. Delivery sends them. Your application connects the two and owns the processes.
- [Scopes](https://good-webhooks.dev/docs/concepts/scopes.md): A scope keeps one customer's endpoints and events apart from everyone else's. It never grants access by itself.
- [Delivery guarantees](https://good-webhooks.dev/docs/concepts/delivery-guarantees.md): At least once, no ordering. What a successful publish promises, how retries work, and how endpoint changes affect queued work.
- [Security model](https://good-webhooks.dev/docs/concepts/security.md): Signing secrets, the storage encryption key, destination checks, and the boundaries your application must enforce.

## Guides

- [Publish events](https://good-webhooks.dev/docs/guides/publish.md): Define a typed event catalog, publish with idempotency keys, reach the right customer, and commit events with your own database writes.
- [Transactional recipient selection](https://good-webhooks.dev/docs/guides/recipient-selection.md): Choose recipients from your own routing table inside the same PostgreSQL transaction that commits the business write.
- [Manage endpoints](https://good-webhooks.dev/docs/guides/endpoints.md): Register, update, pause, resume, rotate, and remove endpoints with the combined client or the standalone PostgreSQL provider.
- [Receive webhooks](https://good-webhooks.dev/docs/guides/receive.md): Verify the raw request, decode a typed event, and process each event exactly once. Examples for Next.js, Hono, Express, and Node.js.
- [Custom senders](https://good-webhooks.dev/docs/guides/custom-senders.md): Keep your own delivery pipeline and use Good Webhooks endpoint management as its source of recipients and signing secrets.

## Better Auth

- [Better Auth plugin](https://good-webhooks.dev/docs/better-auth.md): Let signed-in users manage their own webhook endpoints through authenticated routes, stored in your existing Better Auth database.
- [Better Auth quick start](https://good-webhooks.dev/docs/better-auth/quick-start.md): Create a user, register a personal endpoint through authenticated routes, and list it. One file, SQLite, no PostgreSQL.
- [Permissions](https://good-webhooks.dev/docs/better-auth/permissions.md): How the plugin authorizes personal, organization, application, and custom scopes on every route.
- [Add delivery to Better Auth](https://good-webhooks.dev/docs/better-auth/delivery.md): Keep Better Auth as the source of endpoints and send events with the PostgreSQL delivery engine from a separate worker.
- [Database adapters](https://good-webhooks.dev/docs/better-auth/database-adapters.md): Which Better Auth adapters the plugin is verified against, what the tests cover, and what they do not.

## Operations

- [Production checklist](https://good-webhooks.dev/docs/operations/production.md): Everything to settle before real customers receive webhooks, with a link to the details for each item.
- [Migrations](https://good-webhooks.dev/docs/operations/migrations.md): Pick the SQL for the components you run, apply it with your own migration runner, and keep runtime schema names in sync.
- [Run workers](https://good-webhooks.dev/docs/operations/workers.md): Start delivery explicitly, supervise it, and shut it down without losing in-flight work.
- [Retries and replay](https://good-webhooks.dev/docs/operations/retries-and-replay.md): Inspect delivery history, tell receiver failures from provider failures, and replay an event without changing its identity.
- [Failure behavior](https://good-webhooks.dev/docs/operations/failure-behavior.md): What happens when a worker crashes, the database drops, a receiver hangs, or a deploy restarts everything. Each statement here is checked by a test in the repository.
- [Performance](https://good-webhooks.dev/docs/operations/performance.md): Measured publish and delivery throughput for a fixed profile on one machine, how it was measured, and what the numbers do not say.
- [Retention and cleanup](https://good-webhooks.dev/docs/operations/retention.md): Prune expired events, deliveries, and attempts on a schedule you control.
- [Key rotation](https://good-webhooks.dev/docs/operations/key-rotation.md): Rotate a receiver's signing secret with an overlap, and rotate storage encryption keys without changing what receivers verify.
- [Compatibility](https://good-webhooks.dev/docs/operations/compatibility.md): Supported runtimes and databases, what each release promises, and how to upgrade.

## Reference

- [API reference](https://good-webhooks.dev/docs/reference.md): Every public entry point, what it exports, and where its contract is documented.
- [Core](https://good-webhooks.dev/docs/reference/core.md): Compose endpoint management and PostgreSQL delivery.
- [Delivery](https://good-webhooks.dev/docs/reference/delivery.md): Publication, delivery history, worker execution, and PostgreSQL sender options.
- [Management contracts](https://good-webhooks.dev/docs/reference/management.md): Shared endpoint lifecycle, sender reads, and custom storage interfaces.
- [PostgreSQL management](https://good-webhooks.dev/docs/reference/postgres.md): Standalone management storage and encryption options.
- [Better Auth server](https://good-webhooks.dev/docs/reference/better-auth.md): Authenticated endpoint routes and the trusted management provider.
- [Better Auth client](https://good-webhooks.dev/docs/reference/better-auth-client.md): Client methods, event-name inference, and JSON result types.
- [Receiver verification](https://good-webhooks.dev/docs/reference/verify.md): Authenticate raw request bytes and decode a typed webhook event.
- [PostgreSQL migrations](https://good-webhooks.dev/docs/reference/migrations.md): Fresh-install and upgrade SQL, component selection, custom schemas, and exported SQL assets.
- [Errors](https://good-webhooks.dev/docs/reference/errors.md): Expected operation errors and failures recorded in delivery history.

## Optional

- [Use with AI agents](https://good-webhooks.dev/docs/ai.md): Give coding agents the docs as Markdown, an Agent Skill, an MCP server, the rules they most often get wrong, and prompts that work.
- [Changelog](https://github.com/pplytas/good-webhooks/blob/main/CHANGELOG.md)
- [Releases](https://github.com/pplytas/good-webhooks/releases)