Upgrade from 0.x to 1.0

1.0.0-rc.1 is out on the rc tag and needs no code change or SQL from 0.7.0. 1.0.0 is planned for early December 2026 and is planned to need none either.

Read the sections in order from the version you run. Each one lists the breaking changes and the steps for that release. Follow the rollout order whenever a step needs SQL.

0.4.x to 0.5.0Copy Anchor Link

0.5.0 is a breaking minor that moves the schema to version 6. Changelog.

Breaking changes:

• check() refuses schema 5.
• A pause resets the delivery's retry window (ADR 0015). Paused deliveries keep their full retry.maxAgeMs after resume, and a worker must run during the pause.
• ManagementRepository.create(scope, endpoint, { limit }) takes an options object instead of a third limit argument.
• StoredEndpoint gains encryptedHeaders.
• Built-in management needs no code change.

Steps:

1. Run getPostgresUpgrade({ from: 5 }) or migrations/upgrades/006-all.sql. The step locks the deliveries table while it backfills, so prune first. Older schemas and separate namespaces are covered in migrations.
2. With Better Auth, run your Better Auth migration for the new optional encryptedHeaders field.
3. Restart producers, then workers, on 0.5.0.
4. A custom ManagementRepository implements create(scope, endpoint, { limit }) and enforces the limit.
5. A custom ManagementRepository stores StoredEndpoint.encryptedHeaders as is.

0.5.0 to 0.6.0Copy Anchor Link

0.6.0 needs no SQL and has no breaking changes. Changelog.

Changed behavior:

• Management reads decrypt stored headers. A rotated standalone storage key needs decryptionKeys for get() and list() too.
• The worker sends headers that a custom EndpointSource returns, and defers a delivery when a header uses a reserved name.

Steps:

1. Restart producers, then workers, on 0.6.0. Better Auth needs no migration.
2. If you rotated the standalone storage key, keep the old key in decryptionKeys wherever management calls get() or list().
3. A custom EndpointSource that returns headers must avoid the reserved names, because the worker defers a delivery that carries one.

0.6.0 to 0.7.0Copy Anchor Link

0.7.0 adds no features and changes no default. It moves the schema to version 7 for one index that keeps prune() fast on large history (#153). Changelog.

Breaking changes:

• check() refuses schema 6.

Steps:

1. Run getPostgresUpgrade({ from: 6 }) or migrations/upgrades/007-all.sql. Building the index blocks writes to the deliveries table while it reads the table once. On a large table, build it concurrently first.
2. Restart producers, then workers, on 0.7.0. Better Auth needs no migration.

0.7.0 to 1.0.0Copy Anchor Link

1.0.0-rc.1 has no breaking changes, no code change, and no SQL. It keeps schema 7. Changelog.

Steps:

1. Install good-webhooks@rc and restart producers, then workers. Better Auth needs no migration.

Moving from 1.0.0-rc.1 to 1.0.0 is planned to need no migration.