Examples
Two complete applications that install the published package and show the full path from a business action to a verified webhook.
Both applications live in the repository under examples/. They are independent npm projects that install good-webhooks from npm, so you can copy either one into your own repository.
Order fulfillment
A shop sends orders to a warehouse. Transactional publication, retries against a failing receiver, replay, and shipment deduplication.
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
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
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
Use Node.js 24, npm, and Docker with Compose. In the example directory:
npm ci
docker compose up -d --wait
npm run setup
npm run devOpen 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.
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
The library package ships short, type-checked examples that the docs include verbatim:
| Example | Shows |
|---|---|
examples/basic | Rollback, retry, replay, and receiver deduplication |
examples/transactions | Payload-dependent recipient selection in a transaction |
examples/better-auth | Auth instance, delivery engine, and worker split |
examples/operations | Supervised worker and bounded cleanup entrypoints |