Delivery

good-webhooks/delivery is the PostgreSQL sender: it publishes events, records deliveries, and runs workers against any endpoint source.

import { createDelivery } from 'good-webhooks/delivery'
import type {
  DeliveryEngine,
  DeliveryOptions,
  EndpointSource,
  EndpointResolution,
  ManagementScope,
} from 'good-webhooks/delivery'

Shared event, database, query, and result types come from good-webhooks. Every method on this page is also on the createWebhooks() client.

createDeliveryCopy Anchor Link

createDelivery<const E extends EventDefinitions>(options: DeliveryOptions<E>): DeliveryEngine<E>

import { createDelivery } from 'good-webhooks/delivery'
import { createPostgresManagement } from 'good-webhooks/management/postgres'
import { Pool } from 'pg'
import { z } from 'zod'

const database = new Pool({ connectionString: process.env.DATABASE_URL })
const events = {
  'invoice.paid': z.object({ invoiceId: z.string(), amount: z.number().int() }),
}
const management = createPostgresManagement({
  database,
  eventTypes: Object.keys(events),
  encryptionKey: process.env.WEBHOOK_ENCRYPTION_KEY!,
})

export const delivery = createDelivery({ database, events, source: management.source })

Any EndpointSource works as source, including Better Auth management. The constructor starts no work.

Event names match ^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,119}$. The constructor validates each event's Standard Schema interface. Any invalid option throws INVALID_CONFIG. Delivery guarantees explains how retry plays out.

The delivery objectCopy Anchor Link

The delivery object has the following fields. This table is generated from the public DeliveryOptions type.

publishCopy Anchor Link

publish(input: PublishInput<E>, options?: PublishOptions): Promise<PublishResult>

import { delivery } from './delivery.js'

const { eventId, deliveryCount, duplicate } = await delivery.publish({
  type: 'invoice.paid',
  data: { invoiceId: 'inv_123', amount: 4200 },
  idempotencyKey: 'invoice.paid:inv_123',
})

The stored body is { id, type, occurredAt, data }. id is the event UUID and occurredAt is an ISO timestamp assigned during publication.

The event and its original deliveries commit atomically within delivery storage. A caller-owned transaction stays uncommitted when publish returns. The transaction and recipient guarantees also apply to duplicate publication. The publish guide shows idempotency keys and transactions in context.

deliveriesCopy Anchor Link

deliveries.list(query?: DeliveryQuery): Promise<Page<Delivery>>
deliveries.get(id: string): Promise<DeliveryDetail>
deliveries.replay(id: string): Promise<Delivery>

import { delivery } from './delivery.js'

const page = await delivery.deliveries.list({ status: 'failed', limit: 25 })
const detail = await delivery.deliveries.get(page.items[0]!.id)
if (detail.replayOf === null) await delivery.deliveries.replay(detail.id)

listCopy Anchor Link

list returns newest delivery IDs first. The result is { items, nextCursor }; nextCursor: null marks the final page. Invalid query values throw INVALID_INPUT.

getCopy Anchor Link

get returns the delivery with its attempts array in attempt-number order. Delivery IDs are positive PostgreSQL bigint strings. A missing record in the selected scope produces NOT_FOUND.

replayCopy Anchor Link

replay sends the original event to the same endpoint again as a new delivery. It keeps the event ID and body and gets a new delivery ID and retry budget. See retries and replay.

Delivery and attempt recordsCopy Anchor Link

deliverySettingsCopy Anchor Link

deliverySettings.get(endpointId: string): Promise<{ maxInFlight: number }>
deliverySettings.set(endpointId: string, settings: { maxInFlight: number }): Promise<{ maxInFlight: number }>

import { delivery } from './delivery.js'

const endpointId = 'ENDPOINT_ID' // From endpoints.create()
await delivery.deliverySettings.set(endpointId, { maxInFlight: 4 })

Stores sender-owned concurrency settings separately from endpoint records. Active and paused endpoints accept settings. Missing or deleted endpoints produce NOT_FOUND. An out-of-range value produces INVALID_INPUT.

These settings apply to all workers sharing the same delivery database and schema. They are distinct from the delivery.concurrency limit on each batch.

workerCopy Anchor Link

worker.runOnce(options?: {
	signal?: AbortSignal
	shutdownGraceMs?: number
}): Promise<WorkerResult>
worker.run(options: {
	signal: AbortSignal
	onError?: (error: unknown) => void
	pollIntervalMs?: number
	shutdownGraceMs?: number
}): Promise<void>
worker.prune(): Promise<number>

import { delivery } from './delivery.js'

const stop = new AbortController()
process.once('SIGTERM', () => stop.abort())

await delivery.worker.run({
  signal: stop.signal,
  onError: (error) => console.error('Webhook worker batch failed', error),
})

All worker methods cover every scope in the configured delivery database and schema. Workers own neither the host's process signal handlers nor its database pool. The workers guide shows a supervised process.

runOnceCopy Anchor Link

runOnce recovers expired leases and processes one bounded batch. It does not drain the queue. Its WorkerResult contains these counts:

runCopy Anchor Link

run processes batches until its signal aborts. After a batch completes at least one prepared attempt as a success, retry, or terminal failure, the next batch starts immediately. Empty batches and stale-only results wait for pollIntervalMs. Receiver retries keep their configured schedule. Recovery and reservation cleanup alone do not trigger an immediate batch.

Without onError, an internal batch failure stops run. With onError, the loop awaits the callback, then waits for pollIntervalMs before continuing. A callback that throws or rejects stops the loop.

Attempt outcomesCopy Anchor Link

Each retry waits its configured delay plus up to 20% random jitter. A retry that would land after retry.maxAgeMs is not scheduled.

pruneCopy Anchor Link

prune deletes at most 100 expired events and their dependent deliveries and attempts per call. It returns the number of removed events. Live leases or contended locks can defer deletion. It does not run automatically. See retention.

Worker errorsCopy Anchor Link

check and forScopeCopy Anchor Link

check(): Promise<void>
forScope(scope: Scope): Pick<DeliveryEngine<E>, 'publish' | 'deliveries' | 'deliverySettings'>

import { delivery } from './delivery.js'

await delivery.check()
const customer = delivery.forScope({ type: 'organization', id: 'org_123' })
await customer.deliveries.list()

check() verifies delivery schema version 4 and throws SCHEMA_MISMATCH otherwise, naming the SQL to apply. It never applies migrations and does not check management storage.

forScope(scope) returns publish, deliveries, and deliverySettings bound to one named scope. An invalid scope throws INVALID_INPUT. The root methods use application scope. Scope selection does not authorize access. See scopes.