# Examples

> Two complete applications that install the published package and show the full path from a business action to a verified webhook.

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



Both applications live in the repository under [`examples/`](https://github.com/pplytas/good-webhooks/tree/main/examples). They are independent npm projects that install `good-webhooks` from npm, so you can copy either one into your own repository.

- [Order fulfillment](https://github.com/pplytas/good-webhooks/tree/main/examples/order-fulfillment): A shop sends orders to a warehouse. Transactional publication, retries against a failing
receiver, replay, and shipment deduplication.
- [Better Auth billing](https://github.com/pplytas/good-webhooks/tree/main/examples/better-auth-billing): Users sign in, register their own endpoints, and receive invoice events. Real sessions, per-user
scopes, and a separate worker.

## Order fulfillment [#order-fulfillment]

Northstar Supply is a shop connected to a warehouse. Place an order in the browser and watch the worker deliver it.

* The shop commits the order row and the webhook publication in **one PostgreSQL transaction**.
* The warehouse receiver verifies the signature and records the event ID with its shipment.
* Controls let you make the warehouse return `503`, inspect retries, restore it, and **replay** a delivery. Replaying an accepted event leaves the shipment count unchanged.
* A rollback control shows that a failed business transaction produces neither an order nor a queued event.

## Better Auth billing [#better-auth-billing]

A billing application that combines Better Auth endpoint management with PostgreSQL delivery.

* Sign in, register a personal endpoint, create invoice events, and inspect delivery attempts.
* The browser uses the typed client plugin. The server derives the publisher's scope from the session.
* A separate worker process reads the same management records and sends signed events to the local receiver.

## Run locally [#run-locally]

Use Node.js 24, npm, and Docker with Compose. In the example directory:

```sh
npm ci
docker compose up -d --wait
npm run setup
npm run dev
```

Open `http://127.0.0.1:4311` for order fulfillment or `http://127.0.0.1:4312` for billing. The two applications use separate ports and databases, so they can run at the same time.

> **Note.** Keep the generated `.env` file between restarts. It holds the encryption key that protects
> registered endpoint secrets. Setup applies migrations explicitly; starting the app never changes
> the schema.

Each README includes a walkthrough, per-process commands, and test instructions. The examples bind to loopback and permit local HTTP receivers. Before deploying an adapted version, configure authentication, secrets, migrations, worker supervision, and retention for your environment.

## Smaller checked examples [#smaller-checked-examples]

The library package ships short, type-checked examples that the docs include verbatim:

| Example                                                                                                                    | Shows                                                  |
| -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| [`examples/basic`](https://github.com/pplytas/good-webhooks/tree/main/packages/good-webhooks/examples/basic)               | Rollback, retry, replay, and receiver deduplication    |
| [`examples/transactions`](https://github.com/pplytas/good-webhooks/tree/main/packages/good-webhooks/examples/transactions) | Payload-dependent recipient selection in a transaction |
| [`examples/better-auth`](https://github.com/pplytas/good-webhooks/tree/main/packages/good-webhooks/examples/better-auth)   | Auth instance, delivery engine, and worker split       |
| [`examples/operations`](https://github.com/pplytas/good-webhooks/tree/main/packages/good-webhooks/examples/operations)     | Supervised worker and bounded cleanup entrypoints      |