API reference

Every public entry point, what it exports, and where its contract is documented.

The package has eight code entry points and three SQL assets; this section holds the exact contract for each.

import { createWebhooks, generateEncryptionKey, WebhookError } from 'good-webhooks'
import { createDelivery } from 'good-webhooks/delivery'
import { createManagement } from 'good-webhooks/management'
import {
  createPostgresManagement,
  createPostgresManagementRepository,
} from 'good-webhooks/management/postgres'
import { goodWebhooks, createBetterAuthManagement } from 'good-webhooks/better-auth'
import { goodWebhooksClient } from 'good-webhooks/better-auth/client'
import { parseWebhook, verifyWebhook } from 'good-webhooks/verify'
import { getPostgresMigration } from 'good-webhooks/migrations'

Better Auth is an optional peer; only the two better-auth entry points import it.

good-webhooks

createWebhooks, generateEncryptionKey, WebhookError, and the shared types.

good-webhooks/delivery

createDelivery, publication, history, replay, settings, and the worker.

good-webhooks/management

The EndpointManagement, EndpointSource, repository, and cipher contracts.

good-webhooks/management/postgres

createPostgresManagement and its storage encryption options.

good-webhooks/better-auth

The server plugin, its routes, scope authorization, and the trusted provider.

good-webhooks/better-auth/client

The client plugin and its typed methods.

good-webhooks/verify

parseWebhook and verifyWebhook for receivers.

good-webhooks/migrations

getPostgresMigration and the shipped SQL files.

Errors

Every WebhookError code and what it means.

Which process imports what

Process	Imports
Producer and worker	`good-webhooks`, or `good-webhooks/delivery` with a separate management provider
Endpoint management only	`good-webhooks/management/postgres` or `good-webhooks/better-auth`
Browser (Better Auth client)	`good-webhooks/better-auth/client`
Receiver	`good-webhooks/verify`. It loads no database or worker code
Migration tooling	`good-webhooks/migrations` or the `.sql` assets

Conventions

Constructors validate options and return. They never open connections, apply migrations, or start workers.
Expected failures throw WebhookError with a stable code. Database and provider failures can propagate as other error types.
Trusted provider results use Date values. Better Auth route responses use ISO strings.
Scope arguments are null for application scope or { type, id } for a named scope. Selecting a scope never authorizes the caller. See scopes.

SQL assets

Export	Creates
`good-webhooks/migrations/001-initial.sql`	Management and delivery tables in `public`
`good-webhooks/migrations/management.sql`	`webhook_endpoints` only
`good-webhooks/migrations/delivery.sql`	Delivery tables only

Generate the same SQL for another schema with getPostgresMigration().