# API reference

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

Source: https://good-webhooks.dev/docs/reference



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

```ts
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](https://good-webhooks.dev/docs/reference/core.md): createWebhooks, generateEncryptionKey, WebhookError, and the shared types.
- [good-webhooks/delivery](https://good-webhooks.dev/docs/reference/delivery.md): createDelivery, publication, history, replay, settings, and the worker.
- [good-webhooks/management](https://good-webhooks.dev/docs/reference/management.md): The EndpointManagement, EndpointSource, repository, and cipher contracts.
- [good-webhooks/management/postgres](https://good-webhooks.dev/docs/reference/postgres.md): createPostgresManagement and its storage encryption options.
- [good-webhooks/better-auth](https://good-webhooks.dev/docs/reference/better-auth.md): The server plugin, its routes, scope authorization, and the trusted provider.
- [good-webhooks/better-auth/client](https://good-webhooks.dev/docs/reference/better-auth-client.md): The client plugin and its typed methods.
- [good-webhooks/verify](https://good-webhooks.dev/docs/reference/verify.md): parseWebhook and verifyWebhook for receivers.
- [good-webhooks/migrations](https://good-webhooks.dev/docs/reference/migrations.md): getPostgresMigration and the shipped SQL files.
- [Errors](https://good-webhooks.dev/docs/reference/errors.md): Every WebhookError code and what it means.

## Which process imports what [#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 [#conventions]

* Constructors validate options and return. They never open connections, apply migrations, or start workers.
* Expected failures throw [`WebhookError`](https://good-webhooks.dev/docs/reference/errors.md) 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](https://good-webhooks.dev/docs/concepts/scopes.md).

## SQL assets [#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()`](https://good-webhooks.dev/docs/reference/migrations.md).