@objectstack/plugin-webhooks 5.1.0 → 5.2.0

package/src/sys-webhook-delivery.object.ts

@@ -0,0 +1,202 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { Field, ObjectSchema } from '@objectstack/spec/data';
+
+/**
+ * sys_webhook_delivery — Durable outbox row for one HTTP attempt.
+ *
+ * Schema is owned by `@objectstack/plugin-webhooks`. Add it to your stack
+ * via:
+ *
+ *   import { SysWebhookDelivery } from '@objectstack/plugin-webhooks/schema';
+ *   defineStack({ objects: [SysWebhookDelivery, ...], plugins: [...] });
+ *
+ * Designed for the SqlWebhookOutbox claim algorithm:
+ *
+ *   1. Producers INSERT pending rows (dedup'd by (event_id, webhook_id)).
+ *   2. The dispatcher's per-partition lock-holder runs:
+ *        SELECT id WHERE status='pending' AND partition_key=? AND (next_retry_at <= now OR null)
+ *        UPDATE SET status='in_flight' WHERE id IN (...) AND status='pending'  ← atomic claim
+ *        POST to target URL
+ *        UPDATE SET status=success/pending/dead, attempts=attempts+1, ...
+ *
+ * `partition_key` is precomputed on enqueue (hash(webhook_id) mod N) so the
+ * dispatcher can filter cheaply without DB-side hash functions.
+ *
+ * Indexes are tuned for the hot path: `(status, partition_key, next_retry_at)`
+ * is the claim query; `(event_id, webhook_id)` is the dedup uniqueness.
+ *
+ * @namespace sys
+ */
+export const SysWebhookDelivery = ObjectSchema.create({
+    name: 'sys_webhook_delivery',
+    label: 'Webhook Delivery',
+    pluralLabel: 'Webhook Deliveries',
+    icon: 'package',
+    isSystem: true,
+    managedBy: 'config',
+    userActions: { create: false, edit: false, delete: false, import: false },
+    description:
+        'Durable outbox row for one webhook attempt. Managed by @objectstack/plugin-webhooks; do not write directly.',
+    displayNameField: 'id',
+    titleFormat: '{event_type} → {url}',
+    compactLayout: ['event_type', 'url', 'status', 'attempts', 'next_retry_at'],
+
+    listViews: {
+        recent: {
+            type: 'grid',
+            name: 'recent',
+            label: 'Recent',
+            data: { provider: 'object', object: 'sys_webhook_delivery' },
+            columns: ['event_type', 'url', 'status', 'attempts', 'response_code', 'updated_at'],
+            sort: [{ field: 'updated_at', order: 'desc' }],
+            pagination: { pageSize: 50 },
+        },
+        failures: {
+            type: 'grid',
+            name: 'failures',
+            label: 'Failures',
+            data: { provider: 'object', object: 'sys_webhook_delivery' },
+            columns: ['event_type', 'url', 'status', 'attempts', 'response_code', 'error', 'updated_at'],
+            filter: [{ field: 'status', operator: 'in', value: ['failed', 'dead'] }],
+            sort: [{ field: 'updated_at', order: 'desc' }],
+            pagination: { pageSize: 50 },
+        },
+        in_flight: {
+            type: 'grid',
+            name: 'in_flight',
+            label: 'In Flight',
+            data: { provider: 'object', object: 'sys_webhook_delivery' },
+            columns: ['event_type', 'url', 'attempts', 'claimed_by', 'claimed_at'],
+            filter: [{ field: 'status', operator: 'equals', value: 'in_flight' }],
+            sort: [{ field: 'claimed_at', order: 'desc' }],
+            pagination: { pageSize: 50 },
+        },
+        pending: {
+            type: 'grid',
+            name: 'pending',
+            label: 'Pending',
+            data: { provider: 'object', object: 'sys_webhook_delivery' },
+            columns: ['event_type', 'url', 'attempts', 'next_retry_at', 'updated_at'],
+            filter: [{ field: 'status', operator: 'equals', value: 'pending' }],
+            sort: [{ field: 'next_retry_at', order: 'asc' }],
+            pagination: { pageSize: 50 },
+        },
+        by_status: {
+            type: 'grid',
+            name: 'by_status',
+            label: 'By Status',
+            data: { provider: 'object', object: 'sys_webhook_delivery' },
+            columns: ['status', 'event_type', 'url', 'attempts', 'updated_at'],
+            sort: [{ field: 'status', order: 'asc' }, { field: 'updated_at', order: 'desc' }],
+            grouping: { fields: [{ field: 'status', order: 'asc', collapsed: false }] },
+            pagination: { pageSize: 100 },
+        },
+        by_webhook: {
+            type: 'grid',
+            name: 'by_webhook',
+            label: 'By Webhook',
+            data: { provider: 'object', object: 'sys_webhook_delivery' },
+            columns: ['webhook_id', 'event_type', 'status', 'attempts', 'updated_at'],
+            sort: [{ field: 'webhook_id', order: 'asc' }, { field: 'updated_at', order: 'desc' }],
+            grouping: { fields: [{ field: 'webhook_id', order: 'asc', collapsed: true }] },
+            pagination: { pageSize: 100 },
+        },
+        all_deliveries: {
+            type: 'grid',
+            name: 'all_deliveries',
+            label: 'All',
+            data: { provider: 'object', object: 'sys_webhook_delivery' },
+            columns: ['event_type', 'url', 'status', 'attempts', 'response_code', 'updated_at'],
+            sort: [{ field: 'updated_at', order: 'desc' }],
+            pagination: { pageSize: 100 },
+        },
+    },
+
+    fields: {
+        id: Field.text({
+            label: 'Delivery ID',
+            required: true,
+            maxLength: 64,
+            description: 'UUID — also doubles as the receiver-side idempotency key',
+        }),
+
+        webhook_id: Field.text({
+            label: 'Webhook ID',
+            required: true,
+            maxLength: 64,
+            description: 'FK to sys_webhook.id (loosely coupled — denormalised URL/secret on row)',
+        }),
+
+        event_id: Field.text({
+            label: 'Event ID',
+            required: true,
+            maxLength: 128,
+            description: 'Source event id; UNIQUE(event_id, webhook_id) for dedup',
+        }),
+
+        event_type: Field.text({
+            label: 'Event Type',
+            required: true,
+            maxLength: 128,
+            description: 'e.g. data.record.created',
+        }),
+
+        url: Field.text({
+            label: 'Target URL',
+            required: true,
+            maxLength: 2048,
+            description: 'Snapshotted at enqueue so config edits do not rewrite live rows',
+        }),
+
+        method: Field.text({ label: 'Method', required: false, maxLength: 10 }),
+        headers_json: Field.textarea({ label: 'Headers JSON', required: false }),
+        secret: Field.text({ label: 'HMAC Secret', required: false, maxLength: 256 }),
+        timeout_ms: Field.number({ label: 'Timeout (ms)', required: false }),
+        payload_json: Field.textarea({ label: 'Payload JSON', required: true }),
+
+        partition_key: Field.number({
+            label: 'Partition',
+            required: true,
+            description: 'hash(webhook_id) mod partitionCount — precomputed for cheap WHERE',
+        }),
+
+        status: Field.text({
+            label: 'Status',
+            required: true,
+            defaultValue: 'pending',
+            maxLength: 16,
+            description: 'pending | in_flight | success | failed | dead',
+        }),
+
+        attempts: Field.number({
+            label: 'Attempts',
+            required: true,
+            defaultValue: 0,
+            description: 'Number of POST attempts made so far',
+        }),
+
+        claimed_by: Field.text({ label: 'Claimed By', required: false, maxLength: 128 }),
+        claimed_at: Field.number({ label: 'Claimed At (ms)', required: false }),
+        next_retry_at: Field.number({ label: 'Next Retry At (ms)', required: false }),
+        last_attempted_at: Field.number({ label: 'Last Attempted At (ms)', required: false }),
+        response_code: Field.number({ label: 'HTTP Status', required: false }),
+        response_body: Field.textarea({ label: 'Response Body (capped)', required: false }),
+        error: Field.textarea({ label: 'Error', required: false }),
+
+        created_at: Field.number({ label: 'Created At (ms)', required: true }),
+        updated_at: Field.number({ label: 'Updated At (ms)', required: true }),
+    },
+
+    indexes: [
+        { fields: ['event_id', 'webhook_id'], unique: true },
+        // Hot path: claim query
+        { fields: ['status', 'partition_key', 'next_retry_at'] },
+        // Reaper: scan stale in_flight rows by claimed_at
+        { fields: ['status', 'claimed_at'] },
+        { fields: ['webhook_id'] },
+    ],
+});
+
+/** Canonical object name — exported so SqlWebhookOutbox callers can override if needed. */
+export const SYS_WEBHOOK_DELIVERY = 'sys_webhook_delivery' as const;

package/src/webhook-outbox-plugin.ts

@@ -0,0 +1,280 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { Plugin, PluginContext } from '@objectstack/core';
+import type {
+    IClusterService,
+    IDataEngine,
+    IRealtimeService,
+} from '@objectstack/spec/contracts';
+import { SysWebhook } from '@objectstack/platform-objects/integration';
+import { AutoEnqueuer, type AutoEnqueuerOptions } from './auto-enqueuer.js';
+import { WebhookDispatcher, type DispatcherOptions } from './dispatcher.js';
+import { MemoryWebhookOutbox } from './memory-outbox.js';
+import type { IWebhookOutbox } from './outbox.js';
+import {
+    DeliveryRetentionSweeper,
+    type DeliveryRetentionOptions,
+} from './retention.js';
+import { SysWebhookDelivery } from './sys-webhook-delivery.object.js';
+
+export interface WebhookOutboxPluginOptions
+    extends Partial<Omit<DispatcherOptions, 'cluster' | 'outbox' | 'nodeId'>> {
+    /**
+     * Override the outbox backend. If omitted a fresh `MemoryWebhookOutbox`
+     * is used — fine for local development, **not for production**: each
+     * node will see only its own rows.
+     *
+     * Pass a factory if you need the kernel-resolved `IDataEngine`:
+     *
+     * ```ts
+     * outbox: (ctx) => new SqlWebhookOutbox(
+     *   ctx.getService('objectql'), { partitionCount: 8 },
+     * ),
+     * ```
+     */
+    outbox?: IWebhookOutbox | ((ctx: PluginContext) => IWebhookOutbox);
+
+    /**
+     * Stable node id. If omitted, uses `process.env.OBJECTSTACK_NODE_ID`
+     * or a random UUID generated at plugin init.
+     */
+    nodeId?: string;
+
+    /**
+     * If `false`, the plugin registers the outbox/dispatcher services but
+     * does NOT auto-start the loop — useful for tests that want to step
+     * the dispatcher manually via `dispatcher.tick()`.
+     *
+     * Default: true.
+     */
+    autoStart?: boolean;
+
+    /**
+     * Auto-enqueue config. When enabled (default `true` if the realtime
+     * + data engine services are available), the plugin subscribes to
+     * `data.record.*` events emitted by the engine and automatically
+     * enqueues a delivery row for every matching `sys_webhook` row.
+     *
+     * Set `false` to disable and only use the imperative
+     * `outbox.enqueue()` API.
+     */
+    autoEnqueue?: boolean | AutoEnqueuerOptions;
+
+    /**
+     * Retention sweep config. When enabled (default `true` if a SQL
+     * outbox is in use), a periodic timer prunes old `success` and
+     * `dead` rows from `sys_webhook_delivery`.
+     *
+     * Set `false` to disable (e.g. when using `MemoryWebhookOutbox`).
+     */
+    retention?: boolean | DeliveryRetentionOptions;
+}
+
+/**
+ * Wires a persistent, cluster-aware webhook outbox into the kernel.
+ *
+ * Registered services:
+ *   - `webhook.outbox`     → `IWebhookOutbox` (enqueue / claim / ack / list)
+ *   - `webhook.dispatcher` → `WebhookDispatcher` (manual `tick()` if needed)
+ *   - `webhook.autoEnqueuer` → `AutoEnqueuer` when auto-enqueue is on
+ *   - `webhook.retention`    → `DeliveryRetentionSweeper` when retention is on
+ *
+ * End-to-end flow once auto-enqueue is enabled:
+ *
+ *   engine.insert('contact', {...})
+ *     → engine publishes data.record.created via IRealtimeService
+ *     → AutoEnqueuer matches active sys_webhook rows in O(1)
+ *     → outbox.enqueue() runs fire-and-forget (not on the write path)
+ *     → dispatcher claims and POSTs (cluster-coordinated)
+ *
+ * **Cluster requirement** — this plugin depends on the cluster service
+ * (`ClusterServicePlugin`). With the default `memory` driver the
+ * dispatcher works correctly inside a single process; with a real driver
+ * (`@objectstack/service-cluster-redis`) it correctly coordinates work
+ * across nodes.
+ */
+export class WebhookOutboxPlugin implements Plugin {
+    name = 'com.objectstack.plugin-webhook-outbox';
+    version = '1.1.0';
+    type = 'standard' as const;
+    dependencies = ['com.objectstack.service.cluster'];
+
+    private dispatcher: WebhookDispatcher | undefined;
+    private autoEnqueuer: AutoEnqueuer | undefined;
+    private retention: DeliveryRetentionSweeper | undefined;
+    private outboxInstance: IWebhookOutbox | undefined;
+
+    constructor(private readonly options: WebhookOutboxPluginOptions = {}) {}
+
+    async init(ctx: PluginContext): Promise<void> {
+        const cluster = ctx.getService<IClusterService>('cluster');
+        if (!cluster) {
+            throw new Error(
+                'WebhookOutboxPlugin: required service "cluster" not found — register ClusterServicePlugin first',
+            );
+        }
+
+        // Register the schemas this plugin owns at runtime. `sys_webhook`
+        // (config) lives in @objectstack/platform-objects but no other
+        // plugin claims it — the webhook plugin is the natural owner
+        // since it's the consumer of those rows. `sys_webhook_delivery`
+        // (telemetry) is plugin-private. Registering them here means a
+        // stack just needs `plugins: [new WebhookOutboxPlugin(...)]`
+        // and both objects auto-appear in REST/Studio/Setup nav.
+        const manifest = ctx.getService<{ register(m: any): void }>('manifest');
+        if (manifest && typeof manifest.register === 'function') {
+            manifest.register({
+                id: 'com.objectstack.plugin-webhook-outbox.schema',
+                namespace: 'sys',
+                version: this.version,
+                type: 'plugin',
+                scope: 'system',
+                name: 'Webhook Outbox Schemas',
+                description:
+                    'Registers sys_webhook (configuration) and sys_webhook_delivery (durable outbox telemetry).',
+                objects: [SysWebhook, SysWebhookDelivery],
+            });
+        } else {
+            ctx.logger.warn?.(
+                '[webhook-outbox] manifest service unavailable — sys_webhook / sys_webhook_delivery will NOT appear in REST or Studio nav. Register MetadataService before WebhookOutboxPlugin.',
+            );
+        }
+
+        const outbox = this.resolveOutbox(ctx);
+        this.outboxInstance = outbox;
+        const nodeId =
+            this.options.nodeId ??
+            process.env.OBJECTSTACK_NODE_ID ??
+            `node-${Math.random().toString(36).slice(2, 10)}`;
+
+        const dispatcher = new WebhookDispatcher({
+            nodeId,
+            cluster,
+            outbox,
+            partitionCount: this.options.partitionCount,
+            batchSize: this.options.batchSize,
+            intervalMs: this.options.intervalMs,
+            lockTtlMs: this.options.lockTtlMs,
+            claimTtlMs: this.options.claimTtlMs,
+            fetchImpl: this.options.fetchImpl,
+            onAttempt: this.options.onAttempt,
+            rng: this.options.rng,
+            logger: ctx.logger,
+        });
+        this.dispatcher = dispatcher;
+
+        ctx.registerService('webhook.outbox', outbox);
+        ctx.registerService('webhook.dispatcher', dispatcher);
+
+        if (this.options.autoStart !== false) {
+            dispatcher.start();
+        }
+
+        // Loud warning when running with the in-memory outbox in production —
+        // it loses data on restart and never shares rows across nodes.
+        const usingMemoryOutbox = outbox instanceof MemoryWebhookOutbox;
+        if (usingMemoryOutbox && process.env.NODE_ENV === 'production') {
+            ctx.logger.warn?.(
+                '[webhook-outbox] MemoryWebhookOutbox in production — webhook deliveries WILL be lost on process exit. Pass `outbox: (ctx) => new SqlWebhookOutbox(ctx.getService("objectql"), { partitionCount: 8 })` from `@objectstack/plugin-webhooks/sql`.',
+            );
+        }
+
+        // Auto-enqueue + retention need the kernel to be fully ready
+        // before ObjectQL / Realtime services are resolvable.
+        const autoEnqueueOpt = this.options.autoEnqueue ?? true;
+        const retentionOpt = this.options.retention ?? true;
+
+        const needsReadyHook = autoEnqueueOpt !== false || retentionOpt !== false;
+        if (needsReadyHook && typeof (ctx as any).hook === 'function') {
+            (ctx as any).hook('kernel:ready', async () => {
+                await this.bootAutoEnqueue(ctx, autoEnqueueOpt);
+                this.bootRetention(ctx, retentionOpt);
+            });
+        }
+
+        ctx.logger.info?.('[webhook-outbox] initialised', {
+            nodeId,
+            partitions: this.options.partitionCount ?? 8,
+            interval: this.options.intervalMs ?? 250,
+            autoEnqueue: autoEnqueueOpt !== false,
+            retention: retentionOpt !== false,
+        });
+    }
+
+    async dispose(): Promise<void> {
+        await this.autoEnqueuer?.stop();
+        this.retention?.stop();
+        await this.dispatcher?.stop();
+    }
+
+    private resolveOutbox(ctx: PluginContext): IWebhookOutbox {
+        const opt = this.options.outbox;
+        if (!opt) return new MemoryWebhookOutbox();
+        if (typeof opt === 'function') return (opt as (c: PluginContext) => IWebhookOutbox)(ctx);
+        return opt;
+    }
+
+    private async bootAutoEnqueue(
+        ctx: PluginContext,
+        opt: boolean | AutoEnqueuerOptions,
+    ): Promise<void> {
+        if (opt === false) return;
+        const engine = this.tryGetService<IDataEngine>(ctx, ['objectql', 'data']);
+        const realtime = this.tryGetService<IRealtimeService>(ctx, ['realtime']);
+        if (!engine || !realtime) {
+            ctx.logger.warn?.(
+                '[webhook-auto-enqueuer] disabled — ObjectQL or Realtime service not available',
+                { hasEngine: !!engine, hasRealtime: !!realtime },
+            );
+            return;
+        }
+        if (!this.outboxInstance) return;
+
+        const enqOpts = (typeof opt === 'object' ? opt : {}) as AutoEnqueuerOptions;
+        this.autoEnqueuer = new AutoEnqueuer(
+            engine,
+            realtime,
+            this.outboxInstance,
+            { ...enqOpts, logger: ctx.logger },
+        );
+        await this.autoEnqueuer.start();
+        ctx.registerService('webhook.autoEnqueuer', this.autoEnqueuer);
+        ctx.logger.info?.('[webhook-auto-enqueuer] started');
+    }
+
+    private bootRetention(
+        ctx: PluginContext,
+        opt: boolean | DeliveryRetentionOptions,
+    ): void {
+        if (opt === false) return;
+        // Only meaningful for SQL outbox — Memory has its own (process-lifetime) GC.
+        if (this.outboxInstance instanceof MemoryWebhookOutbox) return;
+        const engine = this.tryGetService<IDataEngine>(ctx, ['objectql', 'data']);
+        if (!engine) {
+            ctx.logger.warn?.(
+                '[webhook-retention] disabled — ObjectQL service not available',
+            );
+            return;
+        }
+        const retOpts = (typeof opt === 'object' ? opt : {}) as DeliveryRetentionOptions;
+        this.retention = new DeliveryRetentionSweeper(engine, {
+            ...retOpts,
+            logger: ctx.logger,
+        });
+        this.retention.start();
+        ctx.registerService('webhook.retention', this.retention);
+        ctx.logger.info?.('[webhook-retention] sweeper started');
+    }
+
+    private tryGetService<T>(ctx: PluginContext, names: string[]): T | undefined {
+        for (const n of names) {
+            try {
+                const svc = ctx.getService<T>(n);
+                if (svc) return svc;
+            } catch {
+                // fall through
+            }
+        }
+        return undefined;
+    }
+}

package/tsconfig.json

@@ -1,18 +1,10 @@
 {
   "extends": "../../../tsconfig.json",
   "compilerOptions": {
-    "outDir": "./dist",
-    "rootDir": "./src",
-    "types": [
-      "node"
-    ]
+    "outDir": "dist",
+    "rootDir": "src",
+    "types": ["node"]
   },
-  "include": [
-    "src/**/*"
-  ],
-  "exclude": [
-    "dist",
-    "node_modules",
-    "**/*.test.ts"
-  ]
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
 }

package/tsup.config.ts

@@ -0,0 +1,14 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+    entry: ['src/index.ts', 'src/sql-outbox.ts', 'src/schema.ts'],
+    splitting: true,
+    sourcemap: true,
+    clean: true,
+    dts: true,
+    format: ['esm', 'cjs'],
+    target: 'es2020',
+    external: ['vitest'],
+});

package/dist/index.d.mts

@@ -1,104 +0,0 @@
-import { Plugin, PluginContext } from '@objectstack/core';
-
-/**
- * A single webhook delivery target.
- */
-interface WebhookSink {
-    /** Unique sink id used for log correlation. */
-    id: string;
-    /** Target HTTPS URL. */
-    url: string;
-    /** Optional HMAC-SHA256 secret. When set, `X-Objectstack-Signature: sha256=…` is added. */
-    secret?: string;
-    /**
-     * Restrict to specific object names (logical names, e.g. `lead`, `account`).
-     * Omit / empty → all objects.
-     */
-    objects?: string[];
-    /**
-     * Restrict to specific event types. Omit / empty → all `data.record.*` events.
-     */
-    eventTypes?: string[];
-    /** Extra headers to send (Authorization, Tenant, etc.). */
-    headers?: Record<string, string>;
-    /** Per-request timeout in milliseconds. Default 5000. */
-    timeoutMs?: number;
-    /** Retry attempts on transient failure. Default 3. Set 0 to disable retries. */
-    retries?: number;
-}
-/**
- * Delivery attempt outcome surfaced to in-process listeners / tests.
- */
-type WebhookDeliveryStatus = 'ok' | 'retrying' | 'failed';
-interface WebhookDeliveryRecord {
-    sinkId: string;
-    url: string;
-    eventType: string;
-    object?: string;
-    status: WebhookDeliveryStatus;
-    httpStatus?: number;
-    attempt: number;
-    error?: string;
-}
-/**
- * Plugin configuration.
- *
- * Sinks may be supplied programmatically OR via env vars when none are
- * passed (suitable for 12-factor / Docker deployments):
- *
- *   OBJECTSTACK_WEBHOOK_URL       — single URL, or comma-separated URLs.
- *   OBJECTSTACK_WEBHOOK_SECRET    — HMAC secret applied to all env-sourced URLs.
- *   OBJECTSTACK_WEBHOOK_OBJECTS   — comma-separated object whitelist.
- *   OBJECTSTACK_WEBHOOK_EVENTS    — comma-separated event-type whitelist
- *                                   (e.g. `data.record.created`).
- */
-interface WebhooksPluginOptions {
-    /** Explicit sink list (takes precedence over env vars). */
-    sinks?: WebhookSink[];
-    /** Override fetch (mainly for tests). Defaults to globalThis.fetch. */
-    fetchImpl?: typeof fetch;
-    /** Hook invoked with each delivery outcome (mainly for tests / metrics). */
-    onDelivery?: (record: WebhookDeliveryRecord) => void;
-}
-/**
- * WebhooksPlugin — fan out data.record.* events to external HTTP endpoints.
- *
- * @example
- * ```ts
- * kernel.use(new WebhooksPlugin({
- *   sinks: [
- *     { id: 'crm-sync', url: 'https://hooks.example.com/in',
- *       secret: process.env.HOOK_SECRET, objects: ['lead', 'account'] },
- *   ],
- * }));
- * ```
- */
-declare class WebhooksPlugin implements Plugin {
-    name: string;
-    version: string;
-    type: string;
-    dependencies: string[];
-    private readonly options;
-    private subscriptionIds;
-    private realtime?;
-    private sinks;
-    private logger?;
-    constructor(options?: WebhooksPluginOptions);
-    init(ctx: PluginContext): Promise<void>;
-    start(ctx: PluginContext): Promise<void>;
-    stop(ctx: PluginContext): Promise<void>;
-    /**
-     * Resolve sinks from constructor options, falling back to env vars when
-     * none provided. Exposed for testing.
-     */
-    private resolveSinks;
-    /**
-     * Dispatch a single event to a sink, with HMAC signing, timeout, and
-     * exponential-backoff retry. Failures past the retry budget are logged
-     * but never thrown — webhook delivery must never break the originating
-     * mutation.
-     */
-    private dispatch;
-}
-
-export { type WebhookDeliveryRecord, type WebhookDeliveryStatus, type WebhookSink, WebhooksPlugin, type WebhooksPluginOptions };