@objectstack/plugin-webhooks 4.0.1

package/src/webhooks-plugin.test.ts

@@ -0,0 +1,218 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import crypto from 'node:crypto';
+import { WebhooksPlugin, type WebhookDeliveryRecord } from './webhooks-plugin.js';
+
+/**
+ * Build a minimal in-memory realtime stub that records subscriptions and
+ * exposes a publish() helper for tests.
+ */
+function makeRealtime() {
+  const subs: Array<{
+    id: string;
+    channel: string;
+    handler: (event: any) => Promise<void> | void;
+    options?: any;
+  }> = [];
+  let counter = 0;
+  return {
+    subscribe: vi.fn(async (channel: string, handler: any, options?: any) => {
+      const id = `sub-${++counter}`;
+      subs.push({ id, channel, handler, options });
+      return id;
+    }),
+    unsubscribe: vi.fn(async (id: string) => {
+      const idx = subs.findIndex(s => s.id === id);
+      if (idx >= 0) subs.splice(idx, 1);
+    }),
+    publish: vi.fn(async (event: any) => {
+      for (const sub of [...subs]) {
+        const opts = sub.options ?? {};
+        if (opts.object && event.object !== opts.object) continue;
+        if (opts.eventTypes && opts.eventTypes.length > 0 && !opts.eventTypes.includes(event.type)) continue;
+        await sub.handler(event);
+      }
+    }),
+    _subs: subs,
+  };
+}
+
+function makeCtx(realtime: any) {
+  const hooks: Record<string, Array<() => Promise<void> | void>> = {};
+  return {
+    logger: { info: vi.fn(), warn: vi.fn(), debug: vi.fn(), error: vi.fn() },
+    getService: vi.fn((name: string) => {
+      if (name === 'realtime') return realtime;
+      throw new Error(`unknown service ${name}`);
+    }),
+    hook: vi.fn((name: string, fn: any) => {
+      (hooks[name] ||= []).push(fn);
+    }),
+    _hooks: hooks,
+  } as any;
+}
+
+describe('WebhooksPlugin', () => {
+  beforeEach(() => {
+    delete process.env.OBJECTSTACK_WEBHOOK_URL;
+    delete process.env.OBJECTSTACK_WEBHOOK_SECRET;
+    delete process.env.OBJECTSTACK_WEBHOOK_OBJECTS;
+    delete process.env.OBJECTSTACK_WEBHOOK_EVENTS;
+  });
+  afterEach(() => { vi.restoreAllMocks(); });
+
+  it('stays dormant when no sinks configured', async () => {
+    const realtime = makeRealtime();
+    const ctx = makeCtx(realtime);
+    const plugin = new WebhooksPlugin();
+    await plugin.init(ctx);
+    await plugin.start(ctx);
+    // No kernel:ready hook fired yet, but even if it did there would be no subs.
+    for (const fn of ctx._hooks['kernel:ready'] ?? []) await fn();
+    expect(realtime.subscribe).not.toHaveBeenCalled();
+    expect(ctx.logger.info).toHaveBeenCalledWith(
+      expect.stringContaining('no sinks configured'),
+    );
+  });
+
+  it('subscribes to realtime and POSTs on data.record.created with HMAC signature', async () => {
+    const realtime = makeRealtime();
+    const ctx = makeCtx(realtime);
+    const deliveries: WebhookDeliveryRecord[] = [];
+    const fetchImpl = vi.fn(async (_url: string, init: any) => ({
+      ok: true, status: 200, text: async () => '',
+      headers: new Map(), bodyEcho: init,
+    } as any));
+
+    const plugin = new WebhooksPlugin({
+      sinks: [{ id: 'crm', url: 'https://hooks.example.com/in', secret: 's3cret', objects: ['lead'] }],
+      fetchImpl: fetchImpl as any,
+      onDelivery: (rec) => deliveries.push(rec),
+    });
+    await plugin.init(ctx);
+    await plugin.start(ctx);
+    for (const fn of ctx._hooks['kernel:ready']) await fn();
+
+    expect(realtime.subscribe).toHaveBeenCalledTimes(1);
+    const event = {
+      type: 'data.record.created',
+      object: 'lead',
+      payload: { recordId: 'L1', after: { id: 'L1', name: 'Acme' } },
+      timestamp: new Date().toISOString(),
+    };
+    await realtime.publish(event);
+
+    expect(fetchImpl).toHaveBeenCalledTimes(1);
+    const [, init] = fetchImpl.mock.calls[0]!;
+    expect(init.method).toBe('POST');
+    expect(init.headers['Content-Type']).toBe('application/json');
+    expect(init.headers['X-Objectstack-Event']).toBe('data.record.created');
+    expect(init.headers['X-Objectstack-Object']).toBe('lead');
+    const expectedSig = 'sha256=' + crypto.createHmac('sha256', 's3cret').update(init.body).digest('hex');
+    expect(init.headers['X-Objectstack-Signature']).toBe(expectedSig);
+    expect(JSON.parse(init.body)).toMatchObject({ type: 'data.record.created', object: 'lead' });
+    expect(deliveries[0]).toMatchObject({ status: 'ok', httpStatus: 200, attempt: 1 });
+  });
+
+  it('filters by object whitelist when sink lists multiple objects', async () => {
+    const realtime = makeRealtime();
+    const ctx = makeCtx(realtime);
+    const fetchImpl = vi.fn(async () => ({ ok: true, status: 200 } as any));
+    const plugin = new WebhooksPlugin({
+      sinks: [{ id: 'multi', url: 'https://x', objects: ['lead', 'account'] }],
+      fetchImpl: fetchImpl as any,
+    });
+    await plugin.init(ctx);
+    await plugin.start(ctx);
+    for (const fn of ctx._hooks['kernel:ready']) await fn();
+
+    await realtime.publish({ type: 'data.record.created', object: 'lead', payload: {}, timestamp: '' });
+    await realtime.publish({ type: 'data.record.created', object: 'contact', payload: {}, timestamp: '' });
+    await realtime.publish({ type: 'data.record.created', object: 'account', payload: {}, timestamp: '' });
+
+    expect(fetchImpl).toHaveBeenCalledTimes(2);
+  });
+
+  it('retries on 5xx then succeeds', async () => {
+    const realtime = makeRealtime();
+    const ctx = makeCtx(realtime);
+    const deliveries: WebhookDeliveryRecord[] = [];
+    let calls = 0;
+    const fetchImpl = vi.fn(async () => {
+      calls++;
+      if (calls < 3) return { ok: false, status: 503 } as any;
+      return { ok: true, status: 200 } as any;
+    });
+    const plugin = new WebhooksPlugin({
+      sinks: [{ id: 'flaky', url: 'https://x', retries: 5 }],
+      fetchImpl: fetchImpl as any,
+      onDelivery: (rec) => deliveries.push(rec),
+    });
+    await plugin.init(ctx);
+    await plugin.start(ctx);
+    for (const fn of ctx._hooks['kernel:ready']) await fn();
+    await realtime.publish({ type: 'data.record.updated', object: 'lead', payload: {}, timestamp: '' });
+    expect(fetchImpl).toHaveBeenCalledTimes(3);
+    expect(deliveries.filter(d => d.status === 'retrying').length).toBe(2);
+    expect(deliveries.at(-1)).toMatchObject({ status: 'ok', attempt: 3 });
+  }, 20_000);
+
+  it('does NOT retry on 4xx (permanent rejection)', async () => {
+    const realtime = makeRealtime();
+    const ctx = makeCtx(realtime);
+    const deliveries: WebhookDeliveryRecord[] = [];
+    const fetchImpl = vi.fn(async () => ({ ok: false, status: 401 } as any));
+    const plugin = new WebhooksPlugin({
+      sinks: [{ id: 'auth', url: 'https://x', retries: 5 }],
+      fetchImpl: fetchImpl as any,
+      onDelivery: (r) => deliveries.push(r),
+    });
+    await plugin.init(ctx);
+    await plugin.start(ctx);
+    for (const fn of ctx._hooks['kernel:ready']) await fn();
+    await realtime.publish({ type: 'data.record.deleted', object: 'lead', payload: {}, timestamp: '' });
+    expect(fetchImpl).toHaveBeenCalledTimes(1);
+    expect(deliveries.at(-1)).toMatchObject({ status: 'failed', httpStatus: 401, attempt: 1 });
+  });
+
+  it('reads URL+secret+filters from env vars when no sinks supplied', async () => {
+    process.env.OBJECTSTACK_WEBHOOK_URL = 'https://a.example,https://b.example';
+    process.env.OBJECTSTACK_WEBHOOK_SECRET = 'env-secret';
+    process.env.OBJECTSTACK_WEBHOOK_OBJECTS = 'lead,account';
+    process.env.OBJECTSTACK_WEBHOOK_EVENTS = 'data.record.created';
+    const realtime = makeRealtime();
+    const ctx = makeCtx(realtime);
+    const fetchImpl = vi.fn(async () => ({ ok: true, status: 200 } as any));
+    const plugin = new WebhooksPlugin({ fetchImpl: fetchImpl as any });
+    await plugin.init(ctx);
+    await plugin.start(ctx);
+    for (const fn of ctx._hooks['kernel:ready']) await fn();
+
+    // Two sinks → two realtime subscriptions.
+    expect(realtime.subscribe).toHaveBeenCalledTimes(2);
+    await realtime.publish({ type: 'data.record.created', object: 'lead', payload: {}, timestamp: '' });
+    // Two sinks both fire.
+    expect(fetchImpl).toHaveBeenCalledTimes(2);
+    const [urlA] = fetchImpl.mock.calls[0]!;
+    const [urlB] = fetchImpl.mock.calls[1]!;
+    expect([urlA, urlB].sort()).toEqual(['https://a.example', 'https://b.example']);
+  });
+
+  it('unsubscribes on stop', async () => {
+    const realtime = makeRealtime();
+    const ctx = makeCtx(realtime);
+    const fetchImpl = vi.fn(async () => ({ ok: true, status: 200 } as any));
+    const plugin = new WebhooksPlugin({
+      sinks: [{ id: 'a', url: 'https://x' }],
+      fetchImpl: fetchImpl as any,
+    });
+    await plugin.init(ctx);
+    await plugin.start(ctx);
+    for (const fn of ctx._hooks['kernel:ready']) await fn();
+    expect(realtime._subs).toHaveLength(1);
+    await plugin.stop(ctx);
+    expect(realtime.unsubscribe).toHaveBeenCalled();
+    expect(realtime._subs).toHaveLength(0);
+  });
+});

package/src/webhooks-plugin.ts

@@ -0,0 +1,294 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import crypto from 'node:crypto';
+import type { Plugin, PluginContext } from '@objectstack/core';
+import type {
+  IRealtimeService,
+  RealtimeEventPayload,
+  RealtimeSubscriptionOptions,
+} from '@objectstack/spec/contracts';
+
+/**
+ * A single webhook delivery target.
+ */
+export 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.
+ */
+export type WebhookDeliveryStatus = 'ok' | 'retrying' | 'failed';
+
+export 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`).
+ */
+export 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;
+}
+
+const DEFAULT_TIMEOUT_MS = 5_000;
+const DEFAULT_RETRIES = 3;
+const BACKOFF_BASE_MS = 250;
+const BACKOFF_MAX_MS = 5_000;
+
+/**
+ * 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'] },
+ *   ],
+ * }));
+ * ```
+ */
+export class WebhooksPlugin implements Plugin {
+  name = 'com.objectstack.webhooks';
+  version = '1.0.0';
+  type = 'standard';
+  dependencies = ['com.objectstack.service.realtime'];
+
+  private readonly options: WebhooksPluginOptions;
+  private subscriptionIds: string[] = [];
+  private realtime?: IRealtimeService;
+  private sinks: WebhookSink[] = [];
+  private logger?: PluginContext['logger'];
+
+  constructor(options: WebhooksPluginOptions = {}) {
+    this.options = options;
+  }
+
+  async init(ctx: PluginContext): Promise<void> {
+    this.logger = ctx.logger;
+    this.sinks = this.resolveSinks();
+    if (this.sinks.length === 0) {
+      ctx.logger.info(
+        'WebhooksPlugin: no sinks configured (options.sinks empty and OBJECTSTACK_WEBHOOK_URL unset) — plugin is dormant',
+      );
+      return;
+    }
+    ctx.logger.info(`WebhooksPlugin: ${this.sinks.length} sink(s) configured`);
+  }
+
+  async start(ctx: PluginContext): Promise<void> {
+    if (this.sinks.length === 0) return;
+    ctx.hook('kernel:ready', async () => {
+      try {
+        this.realtime = ctx.getService<IRealtimeService>('realtime');
+      } catch {
+        ctx.logger.warn('WebhooksPlugin: realtime service unavailable — events will not be forwarded');
+        return;
+      }
+
+      // We subscribe once per sink so the realtime service can apply each
+      // sink's object / eventTypes filter at the channel layer where
+      // possible. This also lets us cleanly unsubscribe on stop().
+      for (const sink of this.sinks) {
+        const opts: RealtimeSubscriptionOptions | undefined =
+          (sink.objects && sink.objects.length === 1) ||
+          (sink.eventTypes && sink.eventTypes.length > 0)
+            ? {
+                ...(sink.objects && sink.objects.length === 1 ? { object: sink.objects[0] } : {}),
+                ...(sink.eventTypes && sink.eventTypes.length > 0 ? { eventTypes: sink.eventTypes } : {}),
+              }
+            : undefined;
+        const id = await this.realtime.subscribe(
+          'data.record',
+          async (event) => { await this.dispatch(sink, event); },
+          opts,
+        );
+        this.subscriptionIds.push(id);
+      }
+      ctx.logger.info(`WebhooksPlugin: subscribed ${this.subscriptionIds.length} realtime listener(s)`);
+    });
+  }
+
+  async stop(ctx: PluginContext): Promise<void> {
+    if (!this.realtime) return;
+    for (const id of this.subscriptionIds) {
+      try { await this.realtime.unsubscribe(id); }
+      catch (err) { ctx.logger.debug('WebhooksPlugin: unsubscribe failed', { id, err }); }
+    }
+    this.subscriptionIds = [];
+  }
+
+  /**
+   * Resolve sinks from constructor options, falling back to env vars when
+   * none provided. Exposed for testing.
+   */
+  private resolveSinks(): WebhookSink[] {
+    if (this.options.sinks && this.options.sinks.length > 0) return this.options.sinks;
+
+    const urlEnv = process.env.OBJECTSTACK_WEBHOOK_URL;
+    if (!urlEnv) return [];
+
+    const urls = urlEnv.split(',').map(s => s.trim()).filter(Boolean);
+    const secret = process.env.OBJECTSTACK_WEBHOOK_SECRET;
+    const objectsEnv = process.env.OBJECTSTACK_WEBHOOK_OBJECTS;
+    const eventsEnv = process.env.OBJECTSTACK_WEBHOOK_EVENTS;
+    const objects = objectsEnv ? objectsEnv.split(',').map(s => s.trim()).filter(Boolean) : undefined;
+    const eventTypes = eventsEnv ? eventsEnv.split(',').map(s => s.trim()).filter(Boolean) : undefined;
+
+    return urls.map((url, idx) => ({
+      id: `env-${idx + 1}`,
+      url,
+      ...(secret ? { secret } : {}),
+      ...(objects ? { objects } : {}),
+      ...(eventTypes ? { eventTypes } : {}),
+    }));
+  }
+
+  /**
+   * 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 async dispatch(sink: WebhookSink, event: RealtimeEventPayload): Promise<void> {
+    // Defence in depth: the realtime layer already filters by single-object
+    // subscriptions, but multi-object whitelists are applied here.
+    if (sink.objects && sink.objects.length > 0 && event.object && !sink.objects.includes(event.object)) {
+      return;
+    }
+    if (sink.eventTypes && sink.eventTypes.length > 0 && !sink.eventTypes.includes(event.type)) {
+      return;
+    }
+
+    const fetchImpl = this.options.fetchImpl ?? globalThis.fetch;
+    if (!fetchImpl) {
+      this.logger?.warn('WebhooksPlugin: no fetch implementation available — dropping event', { sinkId: sink.id });
+      return;
+    }
+
+    const body = JSON.stringify(event);
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+      'User-Agent': 'ObjectStack-Webhooks/1.0',
+      'X-Objectstack-Event': event.type,
+      ...(event.object ? { 'X-Objectstack-Object': event.object } : {}),
+      'X-Objectstack-Delivery': crypto.randomUUID(),
+      ...(sink.headers ?? {}),
+    };
+    if (sink.secret) {
+      const sig = crypto.createHmac('sha256', sink.secret).update(body).digest('hex');
+      headers['X-Objectstack-Signature'] = `sha256=${sig}`;
+    }
+
+    const timeoutMs = sink.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const maxAttempts = (sink.retries ?? DEFAULT_RETRIES) + 1;
+
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), timeoutMs);
+      try {
+        const res = await fetchImpl(sink.url, {
+          method: 'POST',
+          headers,
+          body,
+          signal: controller.signal,
+        });
+        clearTimeout(timer);
+        if (res.ok || (res.status >= 400 && res.status < 500)) {
+          // 4xx is "permanent" — don't retry; only 2xx counts as success.
+          const status: WebhookDeliveryStatus = res.ok ? 'ok' : 'failed';
+          this.options.onDelivery?.({
+            sinkId: sink.id, url: sink.url, eventType: event.type,
+            object: event.object, status, httpStatus: res.status, attempt,
+          });
+          if (status === 'failed') {
+            this.logger?.warn('WebhooksPlugin: sink rejected event', {
+              sinkId: sink.id, status: res.status, eventType: event.type,
+            });
+          }
+          return;
+        }
+        // 5xx → fall through to retry.
+        if (attempt === maxAttempts) {
+          this.options.onDelivery?.({
+            sinkId: sink.id, url: sink.url, eventType: event.type, object: event.object,
+            status: 'failed', httpStatus: res.status, attempt,
+          });
+          this.logger?.warn('WebhooksPlugin: max retries exhausted', {
+            sinkId: sink.id, status: res.status, eventType: event.type,
+          });
+          return;
+        }
+        this.options.onDelivery?.({
+          sinkId: sink.id, url: sink.url, eventType: event.type, object: event.object,
+          status: 'retrying', httpStatus: res.status, attempt,
+        });
+      } catch (err: any) {
+        clearTimeout(timer);
+        const errMessage = err?.name === 'AbortError'
+          ? `timeout after ${timeoutMs}ms`
+          : (err?.message ?? String(err));
+        if (attempt === maxAttempts) {
+          this.options.onDelivery?.({
+            sinkId: sink.id, url: sink.url, eventType: event.type, object: event.object,
+            status: 'failed', attempt, error: errMessage,
+          });
+          this.logger?.warn('WebhooksPlugin: delivery failed', {
+            sinkId: sink.id, eventType: event.type, error: errMessage,
+          });
+          return;
+        }
+        this.options.onDelivery?.({
+          sinkId: sink.id, url: sink.url, eventType: event.type, object: event.object,
+          status: 'retrying', attempt, error: errMessage,
+        });
+      }
+      // Exponential backoff with full jitter.
+      const delay = Math.min(BACKOFF_MAX_MS, BACKOFF_BASE_MS * 2 ** (attempt - 1));
+      const jittered = Math.floor(Math.random() * delay);
+      await new Promise(r => setTimeout(r, jittered));
+    }
+  }
+}

package/tsconfig.json

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