@orthacms/webhooks-server 0.5.0

package/dist/lib/infrastructure/webhook-http.client.js

@@ -0,0 +1,225 @@
+"use strict";
+var WebhookHttpClient_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebhookHttpClient = void 0;
+const tslib_1 = require("tslib");
+const common_1 = require("@nestjs/common");
+const node_dns_1 = require("node:dns");
+const webhooks_domain_1 = require("@orthacms/webhooks-domain");
+const undici_1 = require("undici");
+const webhooks_tokens_1 = require("../webhooks.tokens");
+/**
+ * Posts one delivery, under the policy that decides where this server may be
+ * talked into connecting.
+ *
+ * **Why an `undici.Agent` and not `fetch`.** The address has to be checked
+ * *after* the hostname resolves and the connection has to go to that same
+ * address. Global `fetch` gives no hook between the two, so a name that passes
+ * a pre-flight check and then resolves to `169.254.169.254` — DNS rebinding —
+ * connects anyway. A custom `lookup` is the seam where the resolved address is
+ * judged and either handed to the connector or refused.
+ *
+ * Redirects are not followed. A `3xx` is reported as a failed delivery rather
+ * than an invitation to make a second request, because following one is the
+ * simplest way to be walked to an internal address after the first hop passed.
+ */
+let WebhookHttpClient = WebhookHttpClient_1 = class WebhookHttpClient {
+    config;
+    logger = new common_1.Logger(WebhookHttpClient_1.name);
+    /**
+     * One agent for every delivery, so connections are pooled across them.
+     * Built lazily because it captures the policy from injected config.
+     */
+    agent = null;
+    constructor(config) {
+        this.config = config;
+    }
+    /** Sends one delivery and reports what happened. Never throws. */
+    async send(delivery) {
+        const startedAt = Date.now();
+        const body = JSON.stringify(delivery.body);
+        const timestamp = Math.floor(startedAt / 1000);
+        try {
+            // Re-checked on every send, not only when the endpoint was saved:
+            // a hostname re-pointed at a private address afterwards must be
+            // refused here, and the URL policy may have been tightened since.
+            const url = (0, webhooks_domain_1.assertUrlShape)(delivery.url, this.policy());
+            const response = await (0, undici_1.request)(url, {
+                method: 'POST',
+                body,
+                headers: this.headersFor(delivery, body, timestamp),
+                dispatcher: this.dispatcher(),
+                // `request` does not follow redirects unless a redirect
+                // interceptor is added, and none is: a 3xx is reported as a
+                // failed delivery rather than followed, because following one
+                // is the simplest way to be walked to an internal address
+                // after the first hop already passed the address check.
+                headersTimeout: this.config.timeoutMs,
+                bodyTimeout: this.config.timeoutMs
+            });
+            const snippet = await this.readSnippet(response.body);
+            return {
+                statusCode: response.statusCode,
+                retryAfterMs: retryAfterOf(response.headers),
+                error: null,
+                responseSnippet: snippet,
+                durationMs: Date.now() - startedAt
+            };
+        }
+        catch (error) {
+            return {
+                statusCode: null,
+                error: describeFailure(error),
+                responseSnippet: null,
+                durationMs: Date.now() - startedAt
+            };
+        }
+    }
+    /** The URL policy this deployment configured. */
+    policy() {
+        return {
+            allowInsecureUrls: this.config.allowInsecureUrls,
+            allowPrivateNetworks: this.config.allowPrivateNetworks
+        };
+    }
+    /**
+     * The agent, with the address check wired into its DNS lookup.
+     *
+     * `lookup` is called by the connector with the hostname it is about to
+     * connect to; refusing here means the socket is never opened, and the
+     * address that was judged is the address that would have been used.
+     */
+    dispatcher() {
+        if (this.agent)
+            return this.agent;
+        const policy = this.policy();
+        this.agent = new undici_1.Agent({
+            connect: {
+                timeout: this.config.timeoutMs,
+                lookup: (hostname, options, callback) => {
+                    (0, node_dns_1.lookup)(hostname, options, (error, address, family) => {
+                        if (error) {
+                            callback(error, address, family);
+                            return;
+                        }
+                        try {
+                            for (const resolved of toAddressList(address)) {
+                                (0, webhooks_domain_1.assertAddressAllowed)(resolved, policy);
+                            }
+                        }
+                        catch (rejection) {
+                            callback(rejection, address, family);
+                            return;
+                        }
+                        callback(null, address, family);
+                    });
+                }
+            }
+        });
+        return this.agent;
+    }
+    /** The headers one delivery travels with. */
+    headersFor(delivery, body, timestamp) {
+        const headers = {};
+        // The endpoint's own headers go first, so the reserved ones below can
+        // never be overwritten by configuration. `isAllowedCustomHeader` is
+        // also enforced on write; this is the belt to that braces, because a
+        // row could predate the check.
+        for (const [name, value] of Object.entries(delivery.headers)) {
+            if ((0, webhooks_domain_1.isAllowedCustomHeader)(name))
+                headers[name] = value;
+        }
+        headers['content-type'] = 'application/json';
+        headers['user-agent'] = webhooks_domain_1.DELIVERY_USER_AGENT;
+        headers[webhooks_domain_1.DELIVERY_HEADERS.EVENT] = delivery.eventKind;
+        headers[webhooks_domain_1.DELIVERY_HEADERS.DELIVERY] = delivery.deliveryId;
+        headers[webhooks_domain_1.DELIVERY_HEADERS.EVENT_ID] = delivery.eventId;
+        headers[webhooks_domain_1.DELIVERY_HEADERS.ATTEMPT] = String(delivery.attempt);
+        headers[webhooks_domain_1.DELIVERY_HEADERS.SIGNATURE] = (0, webhooks_domain_1.signatureHeader)(delivery.secret, timestamp, body);
+        if (delivery.workspaceId) {
+            headers[webhooks_domain_1.DELIVERY_HEADERS.WORKSPACE] = delivery.workspaceId;
+        }
+        return headers;
+    }
+    /**
+     * Reads at most `responseSnippetBytes` of the body, then abandons the rest.
+     *
+     * A receiver that answers with a gigabyte would otherwise be able to
+     * exhaust this process's memory from the far end of a connection we
+     * initiated.
+     */
+    async readSnippet(body) {
+        const chunks = [];
+        let size = 0;
+        try {
+            for await (const chunk of body) {
+                const buffer = Buffer.isBuffer(chunk)
+                    ? chunk
+                    : Buffer.from(chunk);
+                chunks.push(buffer);
+                size += buffer.length;
+                if (size >= this.config.responseSnippetBytes)
+                    break;
+            }
+        }
+        catch (error) {
+            this.logger.debug(`Could not read the response body: ${describeFailure(error)}`);
+        }
+        finally {
+            // Whether we stopped early or the stream errored, the connection
+            // must not be left half-read or the pooled socket is unusable.
+            body.resume?.();
+        }
+        if (chunks.length === 0)
+            return null;
+        return Buffer.concat(chunks)
+            .subarray(0, this.config.responseSnippetBytes)
+            .toString('utf8');
+    }
+};
+exports.WebhookHttpClient = WebhookHttpClient;
+exports.WebhookHttpClient = WebhookHttpClient = WebhookHttpClient_1 = tslib_1.__decorate([
+    (0, common_1.Injectable)(),
+    tslib_1.__param(0, (0, webhooks_tokens_1.InjectWebhooksConfig)()),
+    tslib_1.__metadata("design:paramtypes", [Object])
+], WebhookHttpClient);
+/**
+ * A `Retry-After` from the response headers, in milliseconds.
+ *
+ * Parsed in the domain so the header's two legal forms live in one place;
+ * `undefined` simply falls back to our own schedule.
+ */
+function retryAfterOf(headers) {
+    const raw = headers['retry-after'];
+    const value = Array.isArray(raw) ? raw[0] : raw;
+    return value ? (0, webhooks_domain_1.parseRetryAfter)(value) : undefined;
+}
+/** `lookup` may hand back one address or a list; normalise to a list. */
+function toAddressList(address) {
+    return typeof address === 'string'
+        ? [address]
+        : address.map((entry) => entry.address);
+}
+/** A failure, phrased for the delivery log rather than for a stack trace. */
+function describeFailure(error) {
+    if (error instanceof webhooks_domain_1.WebhookUrlRejectedError)
+        return error.message;
+    if (error instanceof Error) {
+        const code = error.code;
+        if (code === 'UND_ERR_HEADERS_TIMEOUT' ||
+            code === 'UND_ERR_BODY_TIMEOUT') {
+            return 'The receiver did not respond in time.';
+        }
+        if (code === 'UND_ERR_CONNECT_TIMEOUT') {
+            return 'Could not connect to the receiver in time.';
+        }
+        if (code === 'ENOTFOUND') {
+            return 'The host name could not be resolved.';
+        }
+        if (code === 'ECONNREFUSED') {
+            return 'The receiver refused the connection.';
+        }
+        return error.message;
+    }
+    return String(error);
+}

package/dist/lib/types/webhooks-config.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Configuration for the webhooks plugin.
+ *
+ * Everything here is a deployment concern — how hard the worker is allowed to
+ * push, how long it waits, what it may reach. The endpoints themselves live in
+ * the database, because which systems a CMS notifies is operational data that
+ * changes without a redeploy.
+ */
+export interface WebhooksPluginConfig {
+    /**
+     * How often, in milliseconds, the worker looks for claimable deliveries.
+     * `0` turns delivery off entirely — rows still queue, so a deployment can
+     * run the API without a sender and let one process do the sending.
+     */
+    deliveryIntervalMs?: number;
+    /**
+     * How many deliveries one tick claims. Bounds the burst a single process
+     * aims at receivers, and the memory one tick holds.
+     */
+    batchSize?: number;
+    /** Per-request timeout in milliseconds. */
+    timeoutMs?: number;
+    /** How many attempts a delivery gets before it is given up on. */
+    maxAttempts?: number;
+    /**
+     * How long a completed delivery stays in the log, in days. `0` keeps them
+     * forever — which is a real choice for a low-volume install, and a table
+     * that grows without bound for any other.
+     */
+    retentionDays?: number;
+    /**
+     * How many consecutive dead deliveries switch an endpoint off. Without a
+     * ceiling, a staging URL that was torn down months ago keeps generating six
+     * requests per save for the life of the deployment.
+     */
+    autoDisableAfter?: number;
+    /**
+     * Permit `http://` destinations. Off by default — a signature over
+     * plaintext still leaks the payload to the network path.
+     */
+    allowInsecureUrls?: boolean;
+    /**
+     * Permit loopback, link-local and RFC 1918 destinations. Off by default;
+     * a self-hosted install whose receiver shares the cluster turns it on
+     * deliberately.
+     */
+    allowPrivateNetworks?: boolean;
+    /**
+     * How long a row may sit in `delivering` before the reaper assumes the
+     * worker that claimed it died, in milliseconds. Must comfortably exceed
+     * {@link timeoutMs}, or a slow-but-live request gets reclaimed and sent
+     * twice.
+     */
+    claimTimeoutMs?: number;
+    /** Bytes of the response body kept for the delivery log. */
+    responseSnippetBytes?: number;
+}
+/** Config with every optional filled in — what the services actually read. */
+export type ResolvedWebhooksConfig = Required<WebhooksPluginConfig>;
+/** Defaults chosen to be safe next to someone else's server, not fast. */
+export declare const WEBHOOKS_DEFAULTS: ResolvedWebhooksConfig;
+/** Fills the defaults in, so no service has to repeat a `??`. */
+export declare function resolveWebhooksConfig(config?: WebhooksPluginConfig): ResolvedWebhooksConfig;
+//# sourceMappingURL=webhooks-config.d.ts.map

package/dist/lib/types/webhooks-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks-config.d.ts","sourceRoot":"","sources":["../../../src/lib/types/webhooks-config.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,WAAW,oBAAoB;IACjC;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAE5B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,2CAA2C;IAC3C,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,kEAAkE;IAClE,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;OAGG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAE5B;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAE/B;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,4DAA4D;IAC5D,oBAAoB,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,8EAA8E;AAC9E,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAAC,oBAAoB,CAAC,CAAC;AAEpE,0EAA0E;AAC1E,eAAO,MAAM,iBAAiB,EAAE,sBAc/B,CAAC;AAEF,iEAAiE;AACjE,wBAAgB,qBAAqB,CACjC,MAAM,GAAE,oBAAyB,GAClC,sBAAsB,CAExB"}

package/dist/lib/types/webhooks-config.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WEBHOOKS_DEFAULTS = void 0;
+exports.resolveWebhooksConfig = resolveWebhooksConfig;
+/** Defaults chosen to be safe next to someone else's server, not fast. */
+exports.WEBHOOKS_DEFAULTS = {
+    deliveryIntervalMs: 2_000,
+    batchSize: 20,
+    timeoutMs: 10_000,
+    maxAttempts: 6,
+    retentionDays: 30,
+    autoDisableAfter: 20,
+    allowInsecureUrls: false,
+    allowPrivateNetworks: false,
+    // Three times the request timeout: long enough that a slow receiver is
+    // never reclaimed underneath a live request, short enough that a crashed
+    // worker's rows move again within a minute.
+    claimTimeoutMs: 30_000,
+    responseSnippetBytes: 2_048
+};
+/** Fills the defaults in, so no service has to repeat a `??`. */
+function resolveWebhooksConfig(config = {}) {
+    return { ...exports.WEBHOOKS_DEFAULTS, ...config };
+}

package/dist/lib/utils/webhooks-plugin.d.ts

@@ -0,0 +1,35 @@
+import type { ServerPlugin } from '@orthacms/bootstrap-server';
+import type { WebhooksPluginConfig } from '../types/webhooks-config';
+/** The webhooks plugin, carrying its config alongside the standard shape. */
+export interface WebhooksServerPluginType extends ServerPlugin {
+    /** The configuration this plugin was constructed with. */
+    webhooksConfig: WebhooksPluginConfig;
+}
+/**
+ * Creates the webhooks plugin — outgoing HTTP notifications about content
+ * changes.
+ *
+ * Register it **after** `DatabasePlugin` (the outbox it subscribes to and the
+ * client it injects) and after `IdentityPlugin` (the permissions its routes are
+ * gated on). It owns three tables — `webhook_endpoints`,
+ * `webhook_endpoint_workspaces` and `webhook_deliveries` — and ships their
+ * migrations under its own tracking table.
+ *
+ * It never delivers from inside the outbox subscriber: the subscriber queues
+ * rows, and a worker sends them with no transaction open. See ADR-0016 for why
+ * that separation is a rule rather than an implementation detail.
+ *
+ * @example
+ * ```typescript
+ * createServer({
+ *   plugins: [
+ *     DatabasePlugin({ connectionString: config.database.url }),
+ *     IdentityPlugin(config.plugins.identity),
+ *     ContentPlugin({ types: contentTypes }),
+ *     WebhooksPlugin({ retentionDays: 30 })
+ *   ]
+ * });
+ * ```
+ */
+export declare function WebhooksPlugin(config?: WebhooksPluginConfig): WebhooksServerPluginType;
+//# sourceMappingURL=webhooks-plugin.d.ts.map

package/dist/lib/utils/webhooks-plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks-plugin.d.ts","sourceRoot":"","sources":["../../../src/lib/utils/webhooks-plugin.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAG/D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAErE,6EAA6E;AAC7E,MAAM,WAAW,wBAAyB,SAAQ,YAAY;IAC1D,0DAA0D;IAC1D,cAAc,EAAE,oBAAoB,CAAC;CACxC;AAqDD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,cAAc,CAC1B,MAAM,GAAE,oBAAyB,GAClC,wBAAwB,CAgB1B"}

package/dist/lib/utils/webhooks-plugin.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebhooksPlugin = WebhooksPlugin;
+const node_path_1 = require("node:path");
+const describe_webhooks_api_1 = require("../docs/describe-webhooks-api");
+const webhooks_module_1 = require("../webhooks.module");
+/**
+ * Rejects a configuration that would misbehave rather than fail loudly.
+ *
+ * The bounds here are not style: a zero `batchSize` is a worker that claims
+ * nothing and looks exactly like a worker with nothing to do, and a
+ * `claimTimeoutMs` under the request timeout reclaims deliveries out from under
+ * live requests and sends every slow one twice. Both are far cheaper to catch
+ * at construction than to diagnose from a delivery log.
+ */
+function assertConfig(config) {
+    const positive = [
+        ['batchSize', config.batchSize],
+        ['timeoutMs', config.timeoutMs],
+        ['maxAttempts', config.maxAttempts],
+        ['autoDisableAfter', config.autoDisableAfter],
+        ['claimTimeoutMs', config.claimTimeoutMs],
+        ['responseSnippetBytes', config.responseSnippetBytes]
+    ];
+    for (const [key, value] of positive) {
+        if (value !== undefined && (!Number.isInteger(value) || value < 1)) {
+            throw new Error(`WebhooksPlugin: ${String(key)} must be a positive integer; got ${value}.`);
+        }
+    }
+    // Zero is a real choice for both of these — "do not send from this process"
+    // and "keep the log forever" — so only a negative value is refused.
+    const nonNegative = [
+        ['deliveryIntervalMs', config.deliveryIntervalMs],
+        ['retentionDays', config.retentionDays]
+    ];
+    for (const [key, value] of nonNegative) {
+        if (value !== undefined && (!Number.isInteger(value) || value < 0)) {
+            throw new Error(`WebhooksPlugin: ${String(key)} must be a non-negative integer (0 disables it); got ${value}.`);
+        }
+    }
+    const timeout = config.timeoutMs ?? 10_000;
+    const claim = config.claimTimeoutMs ?? 30_000;
+    if (claim <= timeout) {
+        throw new Error(`WebhooksPlugin: claimTimeoutMs (${claim}) must exceed timeoutMs (${timeout}), ` +
+            'or a delivery still in flight is reclaimed by another worker and sent twice.');
+    }
+}
+/**
+ * Creates the webhooks plugin — outgoing HTTP notifications about content
+ * changes.
+ *
+ * Register it **after** `DatabasePlugin` (the outbox it subscribes to and the
+ * client it injects) and after `IdentityPlugin` (the permissions its routes are
+ * gated on). It owns three tables — `webhook_endpoints`,
+ * `webhook_endpoint_workspaces` and `webhook_deliveries` — and ships their
+ * migrations under its own tracking table.
+ *
+ * It never delivers from inside the outbox subscriber: the subscriber queues
+ * rows, and a worker sends them with no transaction open. See ADR-0016 for why
+ * that separation is a rule rather than an implementation detail.
+ *
+ * @example
+ * ```typescript
+ * createServer({
+ *   plugins: [
+ *     DatabasePlugin({ connectionString: config.database.url }),
+ *     IdentityPlugin(config.plugins.identity),
+ *     ContentPlugin({ types: contentTypes }),
+ *     WebhooksPlugin({ retentionDays: 30 })
+ *   ]
+ * });
+ * ```
+ */
+function WebhooksPlugin(config = {}) {
+    assertConfig(config);
+    return {
+        name: 'webhooks',
+        module: webhooks_module_1.WebhooksModule.forRoot(config),
+        webhooksConfig: config,
+        migrations: {
+            dir: () => (0, node_path_1.join)(__dirname, '../../../migrations'),
+            table: '__drizzle_migrations_webhooks'
+        },
+        // Every response view here is an `interface`, which `@nestjs/swagger`
+        // cannot see — so the scanner emits an empty 200 for each route. This
+        // hook is where the reference learns what a delivery, an endpoint and
+        // a test result actually look like.
+        docs: { decorate: describe_webhooks_api_1.describeWebhooksApi }
+    };
+}

package/dist/lib/webhooks.module.d.ts

@@ -0,0 +1,18 @@
+import { type DynamicModule } from '@nestjs/common';
+import { type WebhooksPluginConfig } from './types/webhooks-config';
+/**
+ * The webhooks plugin's one dynamic module.
+ *
+ * `global: true` like every other plugin here, so a future surface — an MCP
+ * tool that lists endpoints, a copilot read tool — injects these services
+ * rather than growing its own queries over the same three tables.
+ *
+ * Route order matters: `webhooks/:id/deliveries` is registered **before**
+ * `webhooks/:id`, so the literal segment is matched before the parameter that
+ * would otherwise swallow it. The same reason content registers `bulk` ahead of
+ * `:id`.
+ */
+export declare class WebhooksModule {
+    static forRoot(config?: WebhooksPluginConfig): DynamicModule;
+}
+//# sourceMappingURL=webhooks.module.d.ts.map

package/dist/lib/webhooks.module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.module.d.ts","sourceRoot":"","sources":["../../src/lib/webhooks.module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAY5D,OAAO,EAEH,KAAK,oBAAoB,EAC5B,MAAM,yBAAyB,CAAC;AAEjC;;;;;;;;;;;GAWG;AACH,qBACa,cAAc;IACvB,MAAM,CAAC,OAAO,CAAC,MAAM,GAAE,oBAAyB,GAAG,aAAa;CAoCnE"}

package/dist/lib/webhooks.module.js

@@ -0,0 +1,72 @@
+"use strict";
+var WebhooksModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebhooksModule = void 0;
+const tslib_1 = require("tslib");
+const common_1 = require("@nestjs/common");
+const webhooks_tokens_1 = require("./webhooks.tokens");
+const webhook_endpoints_service_1 = require("./application/webhook-endpoints.service");
+const webhook_delivery_repository_1 = require("./infrastructure/webhook-delivery.repository");
+const webhook_delivery_worker_1 = require("./infrastructure/webhook-delivery.worker");
+const webhook_endpoint_repository_1 = require("./infrastructure/webhook-endpoint.repository");
+const webhook_fanout_subscriber_1 = require("./infrastructure/webhook-fanout.subscriber");
+const webhook_http_client_1 = require("./infrastructure/webhook-http.client");
+const webhook_workspaces_purger_1 = require("./infrastructure/purge/webhook-workspaces.purger");
+const webhook_deliveries_controller_1 = require("./http/controllers/webhook-deliveries.controller");
+const webhook_endpoints_controller_1 = require("./http/controllers/webhook-endpoints.controller");
+const webhook_events_controller_1 = require("./http/controllers/webhook-events.controller");
+const webhooks_config_1 = require("./types/webhooks-config");
+/**
+ * The webhooks plugin's one dynamic module.
+ *
+ * `global: true` like every other plugin here, so a future surface — an MCP
+ * tool that lists endpoints, a copilot read tool — injects these services
+ * rather than growing its own queries over the same three tables.
+ *
+ * Route order matters: `webhooks/:id/deliveries` is registered **before**
+ * `webhooks/:id`, so the literal segment is matched before the parameter that
+ * would otherwise swallow it. The same reason content registers `bulk` ahead of
+ * `:id`.
+ */
+let WebhooksModule = WebhooksModule_1 = class WebhooksModule {
+    static forRoot(config = {}) {
+        return {
+            module: WebhooksModule_1,
+            global: true,
+            controllers: [
+                webhook_events_controller_1.WebhookEventsController,
+                webhook_deliveries_controller_1.WebhookDeliveriesController,
+                webhook_endpoints_controller_1.WebhookEndpointsController
+            ],
+            providers: [
+                {
+                    provide: webhooks_tokens_1.WEBHOOKS_CONFIG,
+                    useValue: (0, webhooks_config_1.resolveWebhooksConfig)(config)
+                },
+                webhook_endpoint_repository_1.WebhookEndpointRepository,
+                webhook_delivery_repository_1.WebhookDeliveryRepository,
+                webhook_http_client_1.WebhookHttpClient,
+                webhook_endpoints_service_1.WebhookEndpointsService,
+                // Registers itself with the outbox dispatcher on bootstrap and
+                // does nothing but queue rows.
+                webhook_fanout_subscriber_1.WebhookFanoutSubscriber,
+                // Arms the sender. The only place this plugin touches the
+                // network, and it never holds a transaction while it does.
+                webhook_delivery_worker_1.WebhookDeliveryWorker,
+                // Registers itself with the workspace-delete registry, if the
+                // host mounted workspaces at all.
+                webhook_workspaces_purger_1.WebhookWorkspacesPurger
+            ],
+            exports: [
+                webhooks_tokens_1.WEBHOOKS_CONFIG,
+                webhook_endpoints_service_1.WebhookEndpointsService,
+                webhook_endpoint_repository_1.WebhookEndpointRepository,
+                webhook_delivery_repository_1.WebhookDeliveryRepository
+            ]
+        };
+    }
+};
+exports.WebhooksModule = WebhooksModule;
+exports.WebhooksModule = WebhooksModule = WebhooksModule_1 = tslib_1.__decorate([
+    (0, common_1.Module)({})
+], WebhooksModule);

package/dist/lib/webhooks.tokens.d.ts

@@ -0,0 +1,5 @@
+/** DI token for the plugin's resolved configuration. */
+export declare const WEBHOOKS_CONFIG: unique symbol;
+/** Injects the resolved webhooks configuration. */
+export declare const InjectWebhooksConfig: () => ParameterDecorator;
+//# sourceMappingURL=webhooks.tokens.d.ts.map

package/dist/lib/webhooks.tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.tokens.d.ts","sourceRoot":"","sources":["../../src/lib/webhooks.tokens.ts"],"names":[],"mappings":"AAEA,wDAAwD;AACxD,eAAO,MAAM,eAAe,eAA4B,CAAC;AAEzD,mDAAmD;AACnD,eAAO,MAAM,oBAAoB,QAAO,kBACb,CAAC"}

package/dist/lib/webhooks.tokens.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InjectWebhooksConfig = exports.WEBHOOKS_CONFIG = void 0;
+const common_1 = require("@nestjs/common");
+/** DI token for the plugin's resolved configuration. */
+exports.WEBHOOKS_CONFIG = Symbol('WEBHOOKS_CONFIG');
+/** Injects the resolved webhooks configuration. */
+const InjectWebhooksConfig = () => (0, common_1.Inject)(exports.WEBHOOKS_CONFIG);
+exports.InjectWebhooksConfig = InjectWebhooksConfig;

package/migrations/0000_init_webhooks.sql

@@ -0,0 +1,53 @@
+CREATE TABLE "webhook_deliveries" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"endpoint_id" uuid NOT NULL,
+	"event_id" uuid NOT NULL,
+	"event_kind" text NOT NULL,
+	"workspace_id" uuid,
+	"content_type" text,
+	"payload" jsonb NOT NULL,
+	"status" text DEFAULT 'pending' NOT NULL,
+	"attempts" integer DEFAULT 0 NOT NULL,
+	"next_attempt_at" timestamp with time zone,
+	"claimed_at" timestamp with time zone,
+	"last_status_code" integer,
+	"last_error" text,
+	"response_snippet" text,
+	"duration_ms" integer,
+	"redelivery_of" uuid,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"completed_at" timestamp with time zone
+);
+--> statement-breakpoint
+CREATE TABLE "webhook_endpoint_workspaces" (
+	"endpoint_id" uuid NOT NULL,
+	"workspace_id" uuid NOT NULL,
+	CONSTRAINT "webhook_endpoint_workspaces_endpoint_id_workspace_id_pk" PRIMARY KEY("endpoint_id","workspace_id")
+);
+--> statement-breakpoint
+CREATE TABLE "webhook_endpoints" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"name" text NOT NULL,
+	"url" text NOT NULL,
+	"secret" text NOT NULL,
+	"secret_hint" text NOT NULL,
+	"enabled" boolean DEFAULT true NOT NULL,
+	"event_kinds" jsonb DEFAULT '[]'::jsonb NOT NULL,
+	"content_types" jsonb DEFAULT '[]'::jsonb NOT NULL,
+	"all_workspaces" boolean DEFAULT false NOT NULL,
+	"headers" jsonb DEFAULT '{}'::jsonb NOT NULL,
+	"disabled_reason" text,
+	"consecutive_failures" integer DEFAULT 0 NOT NULL,
+	"created_by" uuid,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE "webhook_deliveries" ADD CONSTRAINT "webhook_deliveries_endpoint_id_webhook_endpoints_id_fk" FOREIGN KEY ("endpoint_id") REFERENCES "public"."webhook_endpoints"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "webhook_endpoint_workspaces" ADD CONSTRAINT "webhook_endpoint_workspaces_endpoint_id_webhook_endpoints_id_fk" FOREIGN KEY ("endpoint_id") REFERENCES "public"."webhook_endpoints"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+CREATE UNIQUE INDEX "webhook_deliveries_endpoint_event_unique" ON "webhook_deliveries" USING btree ("endpoint_id","event_id") WHERE "webhook_deliveries"."redelivery_of" is null;--> statement-breakpoint
+CREATE INDEX "webhook_deliveries_claimable_idx" ON "webhook_deliveries" USING btree ("next_attempt_at") WHERE "webhook_deliveries"."status" in ('pending', 'failed');--> statement-breakpoint
+CREATE INDEX "webhook_deliveries_endpoint_idx" ON "webhook_deliveries" USING btree ("endpoint_id","created_at");--> statement-breakpoint
+CREATE INDEX "webhook_deliveries_completed_idx" ON "webhook_deliveries" USING btree ("completed_at");--> statement-breakpoint
+CREATE INDEX "webhook_endpoint_workspaces_workspace_idx" ON "webhook_endpoint_workspaces" USING btree ("workspace_id");--> statement-breakpoint
+CREATE INDEX "webhook_endpoints_enabled_idx" ON "webhook_endpoints" USING btree ("enabled");