Compatibility
Supported runtimes and databases, what each release promises, and how to upgrade.
Supported configurations
| Component | Supported | Verified in CI |
|---|---|---|
| Node.js | 24 or later | Node.js 24, ESM and CommonJS consumers |
| TypeScript | 5.9.3 or later | 5.9.3 and 7.0, with NodeNext and Bundler resolution |
| PostgreSQL | 16 and 17 | Full integration suite on both |
| Better Auth | >=1.7.7 <1.8.0 | 1.7.7 across the adapter matrix |
Standalone consumers are checked with strict: true and skipLibCheck: false. Better Auth consumers use skipLibCheck for upstream declarations while keeping application-level inference checks. Other JavaScript runtimes are not verified.
Stability policy
Good Webhooks is in beta. The beta series leads to the stable 0.1.0 release; progress is tracked in issue #22.
Public surface
The entry points and every name they export are the public API, together with the shipped SQL files. Imports from dist/ or src/ paths, and anything not reachable from an entry point, are internal and can change without notice. Internal in a type name means the same.
During beta
- Pin the exact version and commit your lockfile. Only the latest beta receives fixes.
- The public API is frozen. A breaking change is allowed only to fix a correctness or security defect. The changelog labels it Breaking, states the migration, and the release is a new beta.
- Behavior that consumers can observe is part of the API: option defaults, error codes, the request format, and the signature scheme.
- The schema is at version
4. Any schema change ships upgrade SQL and a rollout order for producers and workers, never fresh-install SQL alone. - Test producers, workers, and receivers together before rolling out.
From 0.1.0
- Releases follow semantic versioning. While the major version is
0, a minor release may contain breaking changes; a patch release never does. - Breaking means a passing consumer type-check fails, observable runtime behavior changes, a supported runtime or database version is dropped, or SQL must run before upgrading.
- Every breaking change is deprecated in at least one earlier minor with a runtime or type-level warning, and the release notes state the migration.
- The latest minor receives all fixes. Security fixes also reach the previous minor for three months after the next minor ships.
0.1.0claims a stable API and upgrade path. It does not claim verified behavior at high throughput beyond the measured profile; the production checklist and release notes state what has been measured.
Package versions and schema versions
They are independent. Installing a package never runs SQL. The current schema version is 4 for both components, and check() refuses to start against any other. Each schema change ships upgrade SQL through getPostgresUpgrade() and a rollout order in the migrations guide. Do not assume old and new workers can share a changed schema unless the release notes say so, and never assume downgrading is safe.
What stays constant
Delivery is at least once with no ordering guarantee. Signing follows Standard Webhooks. Receivers keep verifying and deduplicating across upgrades. Store signing and encryption keys outside the deployment and retain whatever existing endpoints need.