From d5dc22045da0f609b5de66a187c376fa307bb85e Mon Sep 17 00:00:00 2001
From: dawidurbanski <hi@dawidurbanski.com>
Date: Sun, 21 Dec 2025 19:44:00 +0100
Subject: [PATCH 01/46] feat(core): add health check endpoints for production
 deployments

Add /health (liveness) and /ready (readiness) endpoints to support
container orchestration and load balancer health checks.

- /health returns 200 when server is running
- /ready returns 200 when fully initialized, 503 during startup
- Includes timestamp and component status in responses

Closes #58
---
 packages/core/src/handlers/health.ts          |  62 ++++++
 packages/core/src/handlers/readiness.ts       |  54 +++++
 packages/core/src/server.ts                   |   8 +
 packages/core/src/start-server.ts             |   7 +
 .../integration/health-endpoints.test.ts      | 195 +++++++++++++++++
 .../core/tests/unit/handlers/health.test.ts   | 204 ++++++++++++++++++
 .../tests/unit/handlers/readiness.test.ts     | 146 +++++++++++++
 7 files changed, 676 insertions(+)
 create mode 100644 packages/core/src/handlers/health.ts
 create mode 100644 packages/core/src/handlers/readiness.ts
 create mode 100644 packages/core/tests/integration/health-endpoints.test.ts
 create mode 100644 packages/core/tests/unit/handlers/health.test.ts
 create mode 100644 packages/core/tests/unit/handlers/readiness.test.ts

diff --git a/packages/core/src/handlers/health.ts b/packages/core/src/handlers/health.ts
new file mode 100644
index 0000000..db6690a
--- /dev/null
+++ b/packages/core/src/handlers/health.ts
@@ -0,0 +1,62 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { isReady, getReadinessChecks } from './readiness.js';
+
+export interface HealthResponse {
+  status: 'ok';
+  timestamp: string;
+}
+
+export interface ReadinessResponse {
+  status: 'ready' | 'initializing';
+  timestamp: string;
+  checks: {
+    graphql: boolean;
+    nodeStore: boolean;
+  };
+}
+
+/**
+ * Health check handler (liveness probe).
+ * Returns 200 if the server process is running.
+ */
+export function healthHandler(req: IncomingMessage, res: ServerResponse): void {
+  if (req.method !== 'GET') {
+    res.writeHead(405, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: 'Method not allowed' }));
+    return;
+  }
+
+  const response: HealthResponse = {
+    status: 'ok',
+    timestamp: new Date().toISOString(),
+  };
+
+  res.writeHead(200, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify(response));
+}
+
+/**
+ * Readiness check handler (readiness probe).
+ * Returns 200 if server is ready to accept traffic.
+ * Returns 503 if server is still initializing.
+ */
+export function readyHandler(req: IncomingMessage, res: ServerResponse): void {
+  if (req.method !== 'GET') {
+    res.writeHead(405, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: 'Method not allowed' }));
+    return;
+  }
+
+  const ready = isReady();
+  const checks = getReadinessChecks();
+
+  const response: ReadinessResponse = {
+    status: ready ? 'ready' : 'initializing',
+    timestamp: new Date().toISOString(),
+    checks,
+  };
+
+  const statusCode = ready ? 200 : 503;
+  res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify(response));
+}
diff --git a/packages/core/src/handlers/readiness.ts b/packages/core/src/handlers/readiness.ts
new file mode 100644
index 0000000..b9350f8
--- /dev/null
+++ b/packages/core/src/handlers/readiness.ts
@@ -0,0 +1,54 @@
+/**
+ * Server readiness state tracking for health check endpoints.
+ * Tracks initialization status of server components.
+ */
+
+export interface ReadinessChecks {
+  graphql: boolean;
+  nodeStore: boolean;
+}
+
+/**
+ * Current readiness state of server components.
+ * All components start as not ready.
+ */
+const state: ReadinessChecks = {
+  graphql: false,
+  nodeStore: false,
+};
+
+/**
+ * Update the readiness status of a component.
+ * @param component - The component name ('graphql' or 'nodeStore')
+ * @param ready - Whether the component is ready
+ */
+export function setReady(
+  component: keyof ReadinessChecks,
+  ready: boolean
+): void {
+  state[component] = ready;
+}
+
+/**
+ * Check if all server components are ready.
+ * @returns true if all components are ready, false otherwise
+ */
+export function isReady(): boolean {
+  return state.graphql && state.nodeStore;
+}
+
+/**
+ * Get the current readiness status of all components.
+ * @returns Object with readiness status for each component
+ */
+export function getReadinessChecks(): ReadinessChecks {
+  return { ...state };
+}
+
+/**
+ * Reset readiness state (for testing purposes).
+ */
+export function resetReadiness(): void {
+  state.graphql = false;
+  state.nodeStore = false;
+}
diff --git a/packages/core/src/server.ts b/packages/core/src/server.ts
index 7730fc9..240260d 100644
--- a/packages/core/src/server.ts
+++ b/packages/core/src/server.ts
@@ -2,6 +2,7 @@ import { createServer } from 'node:http';
 import staticHandler from '@/handlers/static.js';
 import graphqlHandler from '@/handlers/graphql.js';
 import graphiqlHandler from '@/handlers/graphiql.js';
+import { healthHandler, readyHandler } from '@/handlers/health.js';
 
 const server = createServer((req, res) => {
   // Add CORS headers for all requests
@@ -16,6 +17,13 @@ const server = createServer((req, res) => {
     return;
   }
 
+  // Health check endpoints (no auth required)
+  if (req.url === '/health') {
+    return healthHandler(req, res);
+  } else if (req.url === '/ready') {
+    return readyHandler(req, res);
+  }
+
   if (req.url === '/graphql') {
     return graphqlHandler(req, res);
   } else if (req.url === '/graphiql') {
diff --git a/packages/core/src/start-server.ts b/packages/core/src/start-server.ts
index e3f166c..f759024 100644
--- a/packages/core/src/start-server.ts
+++ b/packages/core/src/start-server.ts
@@ -2,6 +2,7 @@ import { loadAppConfig, loadPlugins } from '@/loader.js';
 import { createConfig } from '@/config.js';
 import server from '@/server.js';
 import { rebuildHandler, getCurrentSchema } from '@/handlers/graphql.js';
+import { setReady } from '@/handlers/readiness.js';
 import { runCodegen } from '@/codegen.js';
 import { loadEnv } from '@/env.js';
 import { startMockServer } from '@/mocks/index.js';
@@ -88,6 +89,9 @@ export async function startServer(options: StartServerOptions = {}) {
     }
   }
 
+  // Mark node store as ready after plugins have loaded
+  setReady('nodeStore', true);
+
   // Track main app codegen config if present (after collecting plugin names)
   if (userConfig.codegen) {
     codegenConfigs.push({
@@ -115,6 +119,9 @@ export async function startServer(options: StartServerOptions = {}) {
   console.log('🔨 Building GraphQL schema from sourced nodes...');
   await rebuildHandler();
 
+  // Mark GraphQL as ready after schema is built
+  setReady('graphql', true);
+
   // Get the current schema for query generation
   const schema = await getCurrentSchema();
 
diff --git a/packages/core/tests/integration/health-endpoints.test.ts b/packages/core/tests/integration/health-endpoints.test.ts
new file mode 100644
index 0000000..eff4cf9
--- /dev/null
+++ b/packages/core/tests/integration/health-endpoints.test.ts
@@ -0,0 +1,195 @@
+import { describe, it, expect, beforeAll, afterAll, beforeEach } from 'vitest';
+import http, { createServer, type Server } from 'node:http';
+import { healthHandler, readyHandler } from '@/handlers/health.js';
+import { setReady, resetReadiness } from '@/handlers/readiness.js';
+
+function makeRequest(
+  server: Server,
+  path: string,
+  method: string = 'GET'
+): Promise<{
+  statusCode: number;
+  headers: Record<string, string>;
+  body: string;
+}> {
+  return new Promise((resolve, reject) => {
+    const address = server.address();
+    if (!address || typeof address === 'string') {
+      reject(new Error('Server address not available'));
+      return;
+    }
+
+    const req = http.request(
+      {
+        hostname: 'localhost',
+        port: address.port,
+        path,
+        method,
+      },
+      (res: {
+        statusCode: number;
+        headers: Record<string, string>;
+        on: (event: string, callback: (data?: Buffer) => void) => void;
+      }) => {
+        let body = '';
+        res.on('data', (chunk: Buffer) => {
+          body += chunk.toString();
+        });
+        res.on('end', () => {
+          resolve({
+            statusCode: res.statusCode,
+            headers: res.headers as Record<string, string>,
+            body,
+          });
+        });
+      }
+    );
+    req.on('error', reject);
+    req.end();
+  });
+}
+
+describe('health endpoints integration', () => {
+  let server: Server;
+
+  beforeAll(() => {
+    server = createServer((req, res) => {
+      // Add CORS headers
+      res.setHeader('Access-Control-Allow-Origin', '*');
+      res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+      res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+
+      if (req.url === '/health') {
+        return healthHandler(req, res);
+      } else if (req.url === '/ready') {
+        return readyHandler(req, res);
+      }
+
+      res.writeHead(404);
+      res.end('Not found');
+    });
+
+    return new Promise<void>((resolve) => {
+      server.listen(0, () => resolve());
+    });
+  });
+
+  afterAll(() => {
+    return new Promise<void>((resolve) => {
+      server.close(() => resolve());
+    });
+  });
+
+  beforeEach(() => {
+    resetReadiness();
+  });
+
+  describe('/health endpoint', () => {
+    it('should return 200 with JSON response', async () => {
+      const response = await makeRequest(server, '/health');
+
+      expect(response.statusCode).toBe(200);
+      expect(response.headers['content-type']).toBe('application/json');
+
+      const body = JSON.parse(response.body);
+      expect(body.status).toBe('ok');
+      expect(body.timestamp).toBeDefined();
+    });
+
+    it('should return valid ISO 8601 timestamp', async () => {
+      const response = await makeRequest(server, '/health');
+      const body = JSON.parse(response.body);
+
+      const timestamp = new Date(body.timestamp);
+      expect(timestamp.toISOString()).toBe(body.timestamp);
+    });
+
+    it('should include CORS headers', async () => {
+      const response = await makeRequest(server, '/health');
+
+      expect(response.headers['access-control-allow-origin']).toBe('*');
+      expect(response.headers['access-control-allow-methods']).toBe(
+        'GET, POST, OPTIONS'
+      );
+    });
+
+    it('should return 405 for POST request', async () => {
+      const response = await makeRequest(server, '/health', 'POST');
+
+      expect(response.statusCode).toBe(405);
+    });
+  });
+
+  describe('/ready endpoint', () => {
+    it('should return 503 when not ready', async () => {
+      const response = await makeRequest(server, '/ready');
+
+      expect(response.statusCode).toBe(503);
+      expect(response.headers['content-type']).toBe('application/json');
+
+      const body = JSON.parse(response.body);
+      expect(body.status).toBe('initializing');
+      expect(body.checks.graphql).toBe(false);
+      expect(body.checks.nodeStore).toBe(false);
+    });
+
+    it('should return 200 when all components are ready', async () => {
+      setReady('graphql', true);
+      setReady('nodeStore', true);
+
+      const response = await makeRequest(server, '/ready');
+
+      expect(response.statusCode).toBe(200);
+      expect(response.headers['content-type']).toBe('application/json');
+
+      const body = JSON.parse(response.body);
+      expect(body.status).toBe('ready');
+      expect(body.checks.graphql).toBe(true);
+      expect(body.checks.nodeStore).toBe(true);
+    });
+
+    it('should return 503 when only graphql is ready', async () => {
+      setReady('graphql', true);
+
+      const response = await makeRequest(server, '/ready');
+
+      expect(response.statusCode).toBe(503);
+      const body = JSON.parse(response.body);
+      expect(body.status).toBe('initializing');
+      expect(body.checks.graphql).toBe(true);
+      expect(body.checks.nodeStore).toBe(false);
+    });
+
+    it('should return 503 when only nodeStore is ready', async () => {
+      setReady('nodeStore', true);
+
+      const response = await makeRequest(server, '/ready');
+
+      expect(response.statusCode).toBe(503);
+      const body = JSON.parse(response.body);
+      expect(body.status).toBe('initializing');
+      expect(body.checks.graphql).toBe(false);
+      expect(body.checks.nodeStore).toBe(true);
+    });
+
+    it('should include CORS headers', async () => {
+      const response = await makeRequest(server, '/ready');
+
+      expect(response.headers['access-control-allow-origin']).toBe('*');
+    });
+
+    it('should return 405 for POST request', async () => {
+      const response = await makeRequest(server, '/ready', 'POST');
+
+      expect(response.statusCode).toBe(405);
+    });
+
+    it('should return valid ISO 8601 timestamp', async () => {
+      const response = await makeRequest(server, '/ready');
+      const body = JSON.parse(response.body);
+
+      const timestamp = new Date(body.timestamp);
+      expect(timestamp.toISOString()).toBe(body.timestamp);
+    });
+  });
+});
diff --git a/packages/core/tests/unit/handlers/health.test.ts b/packages/core/tests/unit/handlers/health.test.ts
new file mode 100644
index 0000000..498be47
--- /dev/null
+++ b/packages/core/tests/unit/handlers/health.test.ts
@@ -0,0 +1,204 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { healthHandler, readyHandler } from '@/handlers/health.js';
+import { setReady, resetReadiness } from '@/handlers/readiness.js';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+
+function createMockRequest(method: string = 'GET'): IncomingMessage {
+  return {
+    method,
+  } as IncomingMessage;
+}
+
+function createMockResponse(): ServerResponse & {
+  _statusCode: number;
+  _headers: Record<string, string>;
+  _body: string;
+} {
+  const res = {
+    _statusCode: 0,
+    _headers: {} as Record<string, string>,
+    _body: '',
+    writeHead(statusCode: number, headers?: Record<string, string>) {
+      this._statusCode = statusCode;
+      if (headers) {
+        Object.assign(this._headers, headers);
+      }
+      return this;
+    },
+    end(body?: string) {
+      if (body) {
+        this._body = body;
+      }
+    },
+  };
+  return res as unknown as ServerResponse & {
+    _statusCode: number;
+    _headers: Record<string, string>;
+    _body: string;
+  };
+}
+
+describe('healthHandler', () => {
+  it('should return 200 with status ok for GET request', () => {
+    const req = createMockRequest('GET');
+    const res = createMockResponse();
+
+    healthHandler(req, res);
+
+    expect(res._statusCode).toBe(200);
+    expect(res._headers['Content-Type']).toBe('application/json');
+
+    const body = JSON.parse(res._body);
+    expect(body.status).toBe('ok');
+    expect(body.timestamp).toBeDefined();
+  });
+
+  it('should return valid ISO 8601 timestamp', () => {
+    const req = createMockRequest('GET');
+    const res = createMockResponse();
+
+    healthHandler(req, res);
+
+    const body = JSON.parse(res._body);
+    const timestamp = new Date(body.timestamp);
+    expect(timestamp.toISOString()).toBe(body.timestamp);
+  });
+
+  it('should return 405 for POST request', () => {
+    const req = createMockRequest('POST');
+    const res = createMockResponse();
+
+    healthHandler(req, res);
+
+    expect(res._statusCode).toBe(405);
+    const body = JSON.parse(res._body);
+    expect(body.error).toBe('Method not allowed');
+  });
+
+  it('should return 405 for PUT request', () => {
+    const req = createMockRequest('PUT');
+    const res = createMockResponse();
+
+    healthHandler(req, res);
+
+    expect(res._statusCode).toBe(405);
+  });
+
+  it('should return 405 for DELETE request', () => {
+    const req = createMockRequest('DELETE');
+    const res = createMockResponse();
+
+    healthHandler(req, res);
+
+    expect(res._statusCode).toBe(405);
+  });
+});
+
+describe('readyHandler', () => {
+  beforeEach(() => {
+    resetReadiness();
+  });
+
+  it('should return 503 when no components are ready', () => {
+    const req = createMockRequest('GET');
+    const res = createMockResponse();
+
+    readyHandler(req, res);
+
+    expect(res._statusCode).toBe(503);
+    expect(res._headers['Content-Type']).toBe('application/json');
+
+    const body = JSON.parse(res._body);
+    expect(body.status).toBe('initializing');
+    expect(body.checks.graphql).toBe(false);
+    expect(body.checks.nodeStore).toBe(false);
+  });
+
+  it('should return 503 when only graphql is ready', () => {
+    setReady('graphql', true);
+
+    const req = createMockRequest('GET');
+    const res = createMockResponse();
+
+    readyHandler(req, res);
+
+    expect(res._statusCode).toBe(503);
+    const body = JSON.parse(res._body);
+    expect(body.status).toBe('initializing');
+    expect(body.checks.graphql).toBe(true);
+    expect(body.checks.nodeStore).toBe(false);
+  });
+
+  it('should return 503 when only nodeStore is ready', () => {
+    setReady('nodeStore', true);
+
+    const req = createMockRequest('GET');
+    const res = createMockResponse();
+
+    readyHandler(req, res);
+
+    expect(res._statusCode).toBe(503);
+    const body = JSON.parse(res._body);
+    expect(body.status).toBe('initializing');
+    expect(body.checks.graphql).toBe(false);
+    expect(body.checks.nodeStore).toBe(true);
+  });
+
+  it('should return 200 when all components are ready', () => {
+    setReady('graphql', true);
+    setReady('nodeStore', true);
+
+    const req = createMockRequest('GET');
+    const res = createMockResponse();
+
+    readyHandler(req, res);
+
+    expect(res._statusCode).toBe(200);
+    expect(res._headers['Content-Type']).toBe('application/json');
+
+    const body = JSON.parse(res._body);
+    expect(body.status).toBe('ready');
+    expect(body.checks.graphql).toBe(true);
+    expect(body.checks.nodeStore).toBe(true);
+  });
+
+  it('should return valid ISO 8601 timestamp', () => {
+    const req = createMockRequest('GET');
+    const res = createMockResponse();
+
+    readyHandler(req, res);
+
+    const body = JSON.parse(res._body);
+    const timestamp = new Date(body.timestamp);
+    expect(timestamp.toISOString()).toBe(body.timestamp);
+  });
+
+  it('should return 405 for POST request', () => {
+    const req = createMockRequest('POST');
+    const res = createMockResponse();
+
+    readyHandler(req, res);
+
+    expect(res._statusCode).toBe(405);
+    const body = JSON.parse(res._body);
+    expect(body.error).toBe('Method not allowed');
+  });
+
+  it('should return 405 for PUT request', () => {
+    const req = createMockRequest('PUT');
+    const res = createMockResponse();
+
+    readyHandler(req, res);
+
+    expect(res._statusCode).toBe(405);
+  });
+
+  it('should return 405 for DELETE request', () => {
+    const req = createMockRequest('DELETE');
+    const res = createMockResponse();
+
+    readyHandler(req, res);
+
+    expect(res._statusCode).toBe(405);
+  });
+});
diff --git a/packages/core/tests/unit/handlers/readiness.test.ts b/packages/core/tests/unit/handlers/readiness.test.ts
new file mode 100644
index 0000000..07f9364
--- /dev/null
+++ b/packages/core/tests/unit/handlers/readiness.test.ts
@@ -0,0 +1,146 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import {
+  setReady,
+  isReady,
+  getReadinessChecks,
+  resetReadiness,
+} from '@/handlers/readiness.js';
+
+describe('readiness state', () => {
+  beforeEach(() => {
+    resetReadiness();
+  });
+
+  describe('initial state', () => {
+    it('should have all components as false initially', () => {
+      const checks = getReadinessChecks();
+      expect(checks.graphql).toBe(false);
+      expect(checks.nodeStore).toBe(false);
+    });
+
+    it('should not be ready initially', () => {
+      expect(isReady()).toBe(false);
+    });
+  });
+
+  describe('setReady', () => {
+    it('should update graphql status to true', () => {
+      setReady('graphql', true);
+
+      const checks = getReadinessChecks();
+      expect(checks.graphql).toBe(true);
+      expect(checks.nodeStore).toBe(false);
+    });
+
+    it('should update nodeStore status to true', () => {
+      setReady('nodeStore', true);
+
+      const checks = getReadinessChecks();
+      expect(checks.graphql).toBe(false);
+      expect(checks.nodeStore).toBe(true);
+    });
+
+    it('should update graphql status to false', () => {
+      setReady('graphql', true);
+      setReady('graphql', false);
+
+      const checks = getReadinessChecks();
+      expect(checks.graphql).toBe(false);
+    });
+
+    it('should update nodeStore status to false', () => {
+      setReady('nodeStore', true);
+      setReady('nodeStore', false);
+
+      const checks = getReadinessChecks();
+      expect(checks.nodeStore).toBe(false);
+    });
+
+    it('should update both components independently', () => {
+      setReady('graphql', true);
+      setReady('nodeStore', true);
+
+      const checks = getReadinessChecks();
+      expect(checks.graphql).toBe(true);
+      expect(checks.nodeStore).toBe(true);
+    });
+  });
+
+  describe('isReady', () => {
+    it('should return false when no components are ready', () => {
+      expect(isReady()).toBe(false);
+    });
+
+    it('should return false when only graphql is ready', () => {
+      setReady('graphql', true);
+      expect(isReady()).toBe(false);
+    });
+
+    it('should return false when only nodeStore is ready', () => {
+      setReady('nodeStore', true);
+      expect(isReady()).toBe(false);
+    });
+
+    it('should return true when all components are ready', () => {
+      setReady('graphql', true);
+      setReady('nodeStore', true);
+      expect(isReady()).toBe(true);
+    });
+
+    it('should return false after resetting a ready component', () => {
+      setReady('graphql', true);
+      setReady('nodeStore', true);
+      expect(isReady()).toBe(true);
+
+      setReady('graphql', false);
+      expect(isReady()).toBe(false);
+    });
+  });
+
+  describe('getReadinessChecks', () => {
+    it('should return a copy of the state', () => {
+      const checks1 = getReadinessChecks();
+      const checks2 = getReadinessChecks();
+
+      expect(checks1).not.toBe(checks2);
+      expect(checks1).toEqual(checks2);
+    });
+
+    it('should reflect current state', () => {
+      setReady('graphql', true);
+      const checks = getReadinessChecks();
+      expect(checks.graphql).toBe(true);
+      expect(checks.nodeStore).toBe(false);
+    });
+
+    it('should not be affected by mutations to returned object', () => {
+      const checks = getReadinessChecks();
+      checks.graphql = true;
+
+      const freshChecks = getReadinessChecks();
+      expect(freshChecks.graphql).toBe(false);
+    });
+  });
+
+  describe('resetReadiness', () => {
+    it('should reset all components to false', () => {
+      setReady('graphql', true);
+      setReady('nodeStore', true);
+
+      resetReadiness();
+
+      const checks = getReadinessChecks();
+      expect(checks.graphql).toBe(false);
+      expect(checks.nodeStore).toBe(false);
+    });
+
+    it('should make isReady return false', () => {
+      setReady('graphql', true);
+      setReady('nodeStore', true);
+      expect(isReady()).toBe(true);
+
+      resetReadiness();
+      expect(isReady()).toBe(false);
+    });
+  });
+});

From 75b1dc90cfd0a0d0f6a46ba99742a218ba441517 Mon Sep 17 00:00:00 2001
From: dawidurbanski <hi@dawidurbanski.com>
Date: Sun, 21 Dec 2025 19:47:18 +0100
Subject: [PATCH 02/46] chore: add changeset for health check endpoints

---
 .changeset/add-health-endpoints.md | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)
 create mode 100644 .changeset/add-health-endpoints.md

diff --git a/.changeset/add-health-endpoints.md b/.changeset/add-health-endpoints.md
new file mode 100644
index 0000000..c5423f1
--- /dev/null
+++ b/.changeset/add-health-endpoints.md
@@ -0,0 +1,25 @@
+---
+'universal-data-layer': minor
+---
+
+Add health check endpoints for production deployments
+
+Introduces `/health` and `/ready` endpoints to support container orchestration (Kubernetes, Docker Swarm), load balancers, and deployment verification.
+
+**Endpoints:**
+
+- `GET /health` - Liveness probe, returns 200 when server is running
+- `GET /ready` - Readiness probe, returns 200 when fully initialized, 503 during startup
+
+**Response format:**
+
+```json
+// /health
+{ "status": "ok", "timestamp": "2025-12-21T10:30:00Z" }
+
+// /ready (when ready)
+{ "status": "ready", "timestamp": "2025-12-21T10:30:00Z", "checks": { "graphql": true, "nodeStore": true } }
+
+// /ready (during startup)
+{ "status": "initializing", "timestamp": "2025-12-21T10:30:00Z", "checks": { "graphql": false, "nodeStore": false } }
+```

From 99fdc8bd405b562e2afdc66a5b19fc797a58a86f Mon Sep 17 00:00:00 2001
From: dawidurbanski <hi@dawidurbanski.com>
Date: Sun, 21 Dec 2025 19:59:13 +0100
Subject: [PATCH 03/46] feat(core): add graceful shutdown for production
 deployments

Implement proper SIGTERM/SIGINT signal handlers to gracefully shut down
the UDL server, ensuring in-flight requests complete before exit and
resources are properly cleaned up.

- Add shutdown state management module
- Handle SIGTERM and SIGINT signals
- Complete in-flight requests before closing server
- Return 503 on /ready endpoint during shutdown
- Configurable grace period (default: 30 seconds)
- Clean up file watchers and debounce timers on shutdown
- Log shutdown progress to console

Closes #59
---
 .changeset/graceful-shutdown.md               | 12 +++
 packages/core/src/handlers/health.ts          | 19 ++++-
 packages/core/src/handlers/readiness.ts       |  8 +-
 packages/core/src/shutdown.ts                 | 51 ++++++++++++
 packages/core/src/start-server.ts             | 71 +++++++++++++++--
 .../core/tests/unit/handlers/health.test.ts   | 79 +++++++++++++++++++
 .../tests/unit/handlers/readiness.test.ts     | 35 ++++++++
 packages/core/tests/unit/shutdown.test.ts     | 52 ++++++++++++
 8 files changed, 318 insertions(+), 9 deletions(-)
 create mode 100644 .changeset/graceful-shutdown.md
 create mode 100644 packages/core/src/shutdown.ts
 create mode 100644 packages/core/tests/unit/shutdown.test.ts

diff --git a/.changeset/graceful-shutdown.md b/.changeset/graceful-shutdown.md
new file mode 100644
index 0000000..4d7d5bb
--- /dev/null
+++ b/.changeset/graceful-shutdown.md
@@ -0,0 +1,12 @@
+---
+'universal-data-layer': minor
+---
+
+feat(core): add graceful shutdown for production deployments
+
+- Handle SIGTERM and SIGINT signals for graceful shutdown
+- Complete in-flight requests before closing server
+- Return 503 on `/ready` endpoint during shutdown
+- Configurable grace period (default: 30 seconds)
+- Clean up file watchers and resources on shutdown
+- Log shutdown progress to console
diff --git a/packages/core/src/handlers/health.ts b/packages/core/src/handlers/health.ts
index db6690a..c80f76c 100644
--- a/packages/core/src/handlers/health.ts
+++ b/packages/core/src/handlers/health.ts
@@ -1,5 +1,6 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import { isReady, getReadinessChecks } from './readiness.js';
+import { isShuttingDown } from '@/shutdown.js';
 
 export interface HealthResponse {
   status: 'ok';
@@ -7,12 +8,13 @@ export interface HealthResponse {
 }
 
 export interface ReadinessResponse {
-  status: 'ready' | 'initializing';
+  status: 'ready' | 'initializing' | 'shutting_down';
   timestamp: string;
   checks: {
     graphql: boolean;
     nodeStore: boolean;
   };
+  shuttingDown?: boolean;
 }
 
 /**
@@ -38,7 +40,7 @@ export function healthHandler(req: IncomingMessage, res: ServerResponse): void {
 /**
  * Readiness check handler (readiness probe).
  * Returns 200 if server is ready to accept traffic.
- * Returns 503 if server is still initializing.
+ * Returns 503 if server is still initializing or shutting down.
  */
 export function readyHandler(req: IncomingMessage, res: ServerResponse): void {
   if (req.method !== 'GET') {
@@ -47,13 +49,24 @@ export function readyHandler(req: IncomingMessage, res: ServerResponse): void {
     return;
   }
 
+  const shuttingDown = isShuttingDown();
   const ready = isReady();
   const checks = getReadinessChecks();
 
+  let status: ReadinessResponse['status'];
+  if (shuttingDown) {
+    status = 'shutting_down';
+  } else if (ready) {
+    status = 'ready';
+  } else {
+    status = 'initializing';
+  }
+
   const response: ReadinessResponse = {
-    status: ready ? 'ready' : 'initializing',
+    status,
     timestamp: new Date().toISOString(),
     checks,
+    ...(shuttingDown && { shuttingDown: true }),
   };
 
   const statusCode = ready ? 200 : 503;
diff --git a/packages/core/src/handlers/readiness.ts b/packages/core/src/handlers/readiness.ts
index b9350f8..33bf8b3 100644
--- a/packages/core/src/handlers/readiness.ts
+++ b/packages/core/src/handlers/readiness.ts
@@ -3,6 +3,8 @@
  * Tracks initialization status of server components.
  */
 
+import { isShuttingDown } from '@/shutdown.js';
+
 export interface ReadinessChecks {
   graphql: boolean;
   nodeStore: boolean;
@@ -31,9 +33,13 @@ export function setReady(
 
 /**
  * Check if all server components are ready.
- * @returns true if all components are ready, false otherwise
+ * Returns false if shutdown is in progress.
+ * @returns true if all components are ready and not shutting down, false otherwise
  */
 export function isReady(): boolean {
+  if (isShuttingDown()) {
+    return false;
+  }
   return state.graphql && state.nodeStore;
 }
 
diff --git a/packages/core/src/shutdown.ts b/packages/core/src/shutdown.ts
new file mode 100644
index 0000000..20b1c57
--- /dev/null
+++ b/packages/core/src/shutdown.ts
@@ -0,0 +1,51 @@
+/**
+ * Server shutdown state management.
+ * Tracks shutdown state for graceful shutdown handling.
+ */
+
+/**
+ * Options for graceful shutdown.
+ */
+export interface ShutdownOptions {
+  /** Grace period in milliseconds before forcing exit. Default: 30000 (30 seconds) */
+  gracePeriodMs?: number;
+  /** Exit code to use when forcing exit after grace period. Default: 1 */
+  forceExitCode?: number;
+}
+
+/**
+ * Current shutdown state.
+ */
+interface ShutdownState {
+  isShuttingDown: boolean;
+}
+
+/**
+ * Module-level shutdown state.
+ */
+const state: ShutdownState = {
+  isShuttingDown: false,
+};
+
+/**
+ * Check if the server is currently shutting down.
+ * @returns true if shutdown is in progress
+ */
+export function isShuttingDown(): boolean {
+  return state.isShuttingDown;
+}
+
+/**
+ * Set the shutdown state.
+ * @param value - Whether shutdown is in progress
+ */
+export function setShuttingDown(value: boolean): void {
+  state.isShuttingDown = value;
+}
+
+/**
+ * Reset shutdown state (for testing purposes).
+ */
+export function resetShutdownState(): void {
+  state.isShuttingDown = false;
+}
diff --git a/packages/core/src/start-server.ts b/packages/core/src/start-server.ts
index f759024..afd8f49 100644
--- a/packages/core/src/start-server.ts
+++ b/packages/core/src/start-server.ts
@@ -6,18 +6,24 @@ import { setReady } from '@/handlers/readiness.js';
 import { runCodegen } from '@/codegen.js';
 import { loadEnv } from '@/env.js';
 import { startMockServer } from '@/mocks/index.js';
-import { watch } from 'chokidar';
+import { watch, type FSWatcher } from 'chokidar';
 import { fileURLToPath } from 'node:url';
 import { dirname, resolve } from 'node:path';
 import { defaultStore } from '@/nodes/defaultStore.js';
 import { loadManualTestConfigs, type FeatureCodegenInfo } from '@/features.js';
+import { setShuttingDown } from '@/shutdown.js';
 
 export interface StartServerOptions {
   port?: number;
   configPath?: string;
   watch?: boolean;
+  /** Grace period in milliseconds before forcing exit. Default: 30000 (30 seconds) */
+  gracePeriodMs?: number;
 }
 
+/** Default grace period for shutdown (30 seconds, matches Kubernetes default) */
+const DEFAULT_GRACE_PERIOD_MS = 30000;
+
 export async function startServer(options: StartServerOptions = {}) {
   // Load environment variables from .env files FIRST
   // This must happen before startMockServer so credentials can be detected
@@ -144,6 +150,10 @@ export async function startServer(options: StartServerOptions = {}) {
     }
   }
 
+  // Watcher and debounce state - declared outside conditional for shutdown access
+  let fileWatcher: FSWatcher | undefined;
+  let debounceTimer: NodeJS.Timeout | null = null;
+
   // Setup file watcher for hot reloading in dev mode
   // Only when explicitly in development mode
   if (options.watch !== false && process.env['NODE_ENV'] === 'development') {
@@ -173,7 +183,7 @@ export async function startServer(options: StartServerOptions = {}) {
       );
     }
 
-    const watcher = watch([distSrc, manualTestsSrc, ...graphqlWatchPaths], {
+    fileWatcher = watch([distSrc, manualTestsSrc, ...graphqlWatchPaths], {
       ignored: (path: string) => {
         // Ignore dotfiles
         if (/(^|[\\/])\./.test(path)) return true;
@@ -195,7 +205,6 @@ export async function startServer(options: StartServerOptions = {}) {
       },
     });
 
-    let debounceTimer: NodeJS.Timeout | null = null;
     let pendingChangedPaths: Set<string> = new Set();
 
     /**
@@ -237,7 +246,7 @@ export async function startServer(options: StartServerOptions = {}) {
       return affectedConfigs.length > 0 ? affectedConfigs : codegenConfigs;
     }
 
-    watcher.on('change', (path) => {
+    fileWatcher.on('change', (path) => {
       // Normalize path to always use forward slashes
       const normalizedPath = path.replace(/\\/g, '/');
       // Ignore .map files from logging
@@ -311,10 +320,62 @@ export async function startServer(options: StartServerOptions = {}) {
 
     // Clean up watcher on server close
     server.on('close', () => {
-      watcher.close();
+      fileWatcher?.close();
     });
   }
 
+  // Graceful shutdown handler
+  const gracePeriodMs = options.gracePeriodMs ?? DEFAULT_GRACE_PERIOD_MS;
+  let isShuttingDown = false;
+
+  const gracefulShutdown = (signal: string): void => {
+    // Prevent multiple shutdown attempts
+    if (isShuttingDown) {
+      return;
+    }
+    isShuttingDown = true;
+
+    console.log(`\n🛑 Received ${signal}, starting graceful shutdown...`);
+
+    // Mark server as not ready (readiness probe will return 503)
+    setShuttingDown(true);
+
+    // Set up force exit after grace period
+    const forceExitTimeout = setTimeout(() => {
+      console.error('⚠️ Forcing exit after grace period');
+      process.exit(1);
+    }, gracePeriodMs);
+
+    // Unref the timeout so it doesn't keep the process alive
+    forceExitTimeout.unref();
+
+    // Stop accepting new connections and wait for in-flight requests
+    server.close(() => {
+      console.log('✅ HTTP server closed');
+
+      // Clear the force exit timeout
+      clearTimeout(forceExitTimeout);
+
+      // Clean up debounce timer if active
+      if (debounceTimer) {
+        clearTimeout(debounceTimer);
+        debounceTimer = null;
+      }
+
+      // Clean up file watcher
+      if (fileWatcher) {
+        fileWatcher.close();
+      }
+
+      console.log('👋 Shutdown complete');
+      process.exit(0);
+    });
+  };
+
+  // Register signal handlers
+  process.on('SIGTERM', () => gracefulShutdown('SIGTERM'));
+  process.on('SIGINT', () => gracefulShutdown('SIGINT'));
+
   server.listen(port);
   console.log(`🚀 Universal Data Layer server listening on port ${port}`);
   console.log(`📟 GraphQL server available at ${config.endpoint}`);
diff --git a/packages/core/tests/unit/handlers/health.test.ts b/packages/core/tests/unit/handlers/health.test.ts
index 498be47..a2a9d4b 100644
--- a/packages/core/tests/unit/handlers/health.test.ts
+++ b/packages/core/tests/unit/handlers/health.test.ts
@@ -1,6 +1,7 @@
 import { describe, it, expect, beforeEach } from 'vitest';
 import { healthHandler, readyHandler } from '@/handlers/health.js';
 import { setReady, resetReadiness } from '@/handlers/readiness.js';
+import { setShuttingDown, resetShutdownState } from '@/shutdown.js';
 import type { IncomingMessage, ServerResponse } from 'node:http';
 
 function createMockRequest(method: string = 'GET'): IncomingMessage {
@@ -97,6 +98,7 @@ describe('healthHandler', () => {
 describe('readyHandler', () => {
   beforeEach(() => {
     resetReadiness();
+    resetShutdownState();
   });
 
   it('should return 503 when no components are ready', () => {
@@ -201,4 +203,81 @@ describe('readyHandler', () => {
 
     expect(res._statusCode).toBe(405);
   });
+
+  describe('shutdown state', () => {
+    it('should return 503 when shutting down', () => {
+      setReady('graphql', true);
+      setReady('nodeStore', true);
+
+      const req = createMockRequest('GET');
+      const res = createMockResponse();
+
+      // First verify it's ready
+      readyHandler(req, res);
+      expect(res._statusCode).toBe(200);
+
+      // Now trigger shutdown
+      setShuttingDown(true);
+      const res2 = createMockResponse();
+      readyHandler(req, res2);
+
+      expect(res2._statusCode).toBe(503);
+    });
+
+    it('should include shuttingDown: true in response when shutting down', () => {
+      setReady('graphql', true);
+      setReady('nodeStore', true);
+      setShuttingDown(true);
+
+      const req = createMockRequest('GET');
+      const res = createMockResponse();
+
+      readyHandler(req, res);
+
+      const body = JSON.parse(res._body);
+      expect(body.shuttingDown).toBe(true);
+    });
+
+    it('should return status shutting_down when shutting down', () => {
+      setReady('graphql', true);
+      setReady('nodeStore', true);
+      setShuttingDown(true);
+
+      const req = createMockRequest('GET');
+      const res = createMockResponse();
+
+      readyHandler(req, res);
+
+      const body = JSON.parse(res._body);
+      expect(body.status).toBe('shutting_down');
+    });
+
+    it('should not include shuttingDown field when not shutting down', () => {
+      setReady('graphql', true);
+      setReady('nodeStore', true);
+
+      const req = createMockRequest('GET');
+      const res = createMockResponse();
+
+      readyHandler(req, res);
+
+      const body = JSON.parse(res._body);
+      expect(body.shuttingDown).toBeUndefined();
+    });
+
+    it('should still include checks during shutdown', () => {
+      setReady('graphql', true);
+      setReady('nodeStore', true);
+      setShuttingDown(true);
+
+      const req = createMockRequest('GET');
+      const res = createMockResponse();
+
+      readyHandler(req, res);
+
+      const body = JSON.parse(res._body);
+      expect(body.checks.graphql).toBe(true);
+      expect(body.checks.nodeStore).toBe(true);
+    });
+  });
 });
diff --git a/packages/core/tests/unit/handlers/readiness.test.ts b/packages/core/tests/unit/handlers/readiness.test.ts
index 07f9364..c9af4bb 100644
--- a/packages/core/tests/unit/handlers/readiness.test.ts
+++ b/packages/core/tests/unit/handlers/readiness.test.ts
@@ -5,10 +5,12 @@ import {
   getReadinessChecks,
   resetReadiness,
 } from '@/handlers/readiness.js';
+import { setShuttingDown, resetShutdownState } from '@/shutdown.js';
 
 describe('readiness state', () => {
   beforeEach(() => {
     resetReadiness();
+    resetShutdownState();
   });
 
   describe('initial state', () => {
@@ -143,4 +145,37 @@ describe('readiness state', () => {
       expect(isReady()).toBe(false);
     });
   });
+
+  describe('shutdown state integration', () => {
+    it('should return false when shutting down even if all components are ready', () => {
+      setReady('graphql', true);
+      setReady('nodeStore', true);
+      expect(isReady()).toBe(true);
+
+      setShuttingDown(true);
+      expect(isReady()).toBe(false);
+    });
+
+    it('should return true again after shutdown is cancelled', () => {
+      setReady('graphql', true);
+      setReady('nodeStore', true);
+
+      setShuttingDown(true);
+      expect(isReady()).toBe(false);
+
+      setShuttingDown(false);
+      expect(isReady()).toBe(true);
+    });
+
+    it('should return false when shutting down regardless of component state', () => {
+      setShuttingDown(true);
+      expect(isReady()).toBe(false);
+
+      setReady('graphql', true);
+      expect(isReady()).toBe(false);
+
+      setReady('nodeStore', true);
+      expect(isReady()).toBe(false);
+    });
+  });
 });
diff --git a/packages/core/tests/unit/shutdown.test.ts b/packages/core/tests/unit/shutdown.test.ts
new file mode 100644
index 0000000..1610bc1
--- /dev/null
+++ b/packages/core/tests/unit/shutdown.test.ts
@@ -0,0 +1,52 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import {
+  isShuttingDown,
+  setShuttingDown,
+  resetShutdownState,
+} from '@/shutdown.js';
+
+describe('shutdown state', () => {
+  beforeEach(() => {
+    resetShutdownState();
+  });
+
+  describe('initial state', () => {
+    it('should not be shutting down initially', () => {
+      expect(isShuttingDown()).toBe(false);
+    });
+  });
+
+  describe('setShuttingDown', () => {
+    it('should set shutdown state to true', () => {
+      setShuttingDown(true);
+      expect(isShuttingDown()).toBe(true);
+    });
+
+    it('should set shutdown state to false', () => {
+      setShuttingDown(true);
+      setShuttingDown(false);
+      expect(isShuttingDown()).toBe(false);
+    });
+
+    it('should handle multiple true calls', () => {
+      setShuttingDown(true);
+      setShuttingDown(true);
+      expect(isShuttingDown()).toBe(true);
+    });
+  });
+
+  describe('resetShutdownState', () => {
+    it('should reset shutdown state to false', () => {
+      setShuttingDown(true);
+      expect(isShuttingDown()).toBe(true);
+
+      resetShutdownState();
+      expect(isShuttingDown()).toBe(false);
+    });
+
+    it('should be idempotent when already false', () => {
+      resetShutdownState();
+      expect(isShuttingDown()).toBe(false);
+    });
+  });
+});

From 4fc0e8fe734257f7e470ade8d6b4382564e7f762 Mon Sep 17 00:00:00 2001
From: dawidurbanski <hi@dawidurbanski.com>
Date: Sun, 21 Dec 2025 20:18:00 +0100
Subject: [PATCH 04/46] feat(core): add plugin webhook registration API

Extend SourceNodesContext with registerWebhook function, allowing plugins
to register webhook handlers for receiving payloads from external sources.

- Add WebhookRegistry class for managing webhook handlers
- Add WebhookRegistration, WebhookHandler, WebhookHandlerContext types
- Extend loadPlugins and loadConfigFile to pass registerWebhook to plugins
- Export webhook utilities from core package
- Add comprehensive unit tests (33 tests)

Closes #60
---
 .changeset/add-webhook-registration-api.md    |  35 ++
 packages/core/src/index.ts                    |  12 +
 packages/core/src/loader.ts                   |  31 ++
 packages/core/src/nodes/index.ts              |  19 +
 packages/core/src/webhooks/index.ts           |  23 ++
 packages/core/src/webhooks/registry.ts        | 263 ++++++++++++++
 packages/core/src/webhooks/types.ts           | 124 +++++++
 .../core/tests/unit/webhooks/registry.test.ts | 334 ++++++++++++++++++
 8 files changed, 841 insertions(+)
 create mode 100644 .changeset/add-webhook-registration-api.md
 create mode 100644 packages/core/src/webhooks/index.ts
 create mode 100644 packages/core/src/webhooks/registry.ts
 create mode 100644 packages/core/src/webhooks/types.ts
 create mode 100644 packages/core/tests/unit/webhooks/registry.test.ts

diff --git a/.changeset/add-webhook-registration-api.md b/.changeset/add-webhook-registration-api.md
new file mode 100644
index 0000000..d7ec08d
--- /dev/null
+++ b/.changeset/add-webhook-registration-api.md
@@ -0,0 +1,35 @@
+---
+'universal-data-layer': minor
+---
+
+Add plugin webhook registration API
+
+Extends `SourceNodesContext` with `registerWebhook` function, allowing plugins to register webhook handlers that will receive and process incoming webhook payloads from external data sources.
+
+**Usage in plugins:**
+
+```typescript
+export async function sourceNodes({ actions, registerWebhook }) {
+  // Source initial data...
+
+  registerWebhook({
+    path: 'entry-update',
+    handler: async (req, res, context) => {
+      const { body, actions } = context;
+      await actions.createNode(transformEntry(body), { ... });
+      res.writeHead(200);
+      res.end();
+    },
+    verifySignature: (req, body) => {
+      return verifyHmac(body, req.headers['x-signature'], secret);
+    },
+  });
+}
+```
+
+**New exports:**
+
+- `WebhookRegistry` - Central registry for webhook handlers
+- `WebhookRegistrationError` - Error thrown on invalid registration
+- `defaultWebhookRegistry` - Default singleton instance
+- `WebhookRegistration`, `WebhookHandler`, `WebhookHandlerFn`, `WebhookHandlerContext` types
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index f651274..bf79413 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -124,5 +124,17 @@ export {
   type NormalizedResponse as NormalizedGraphQLResponse,
 } from './normalization/index.js';
 
+// Re-export webhook utilities
+export {
+  WebhookRegistry,
+  WebhookRegistrationError,
+  defaultWebhookRegistry,
+  setDefaultWebhookRegistry,
+  type WebhookRegistration,
+  type WebhookHandlerFn,
+  type WebhookHandlerContext,
+  type WebhookHandler,
+} from './webhooks/index.js';
+
 // Export the default server for programmatic usage
 export { default } from './server.js';
diff --git a/packages/core/src/loader.ts b/packages/core/src/loader.ts
index 8bf071d..c5eb915 100644
--- a/packages/core/src/loader.ts
+++ b/packages/core/src/loader.ts
@@ -13,6 +13,11 @@ import type {
   ReferenceResolverConfig,
   EntityKeyConfig,
 } from '@/references/types.js';
+import {
+  defaultWebhookRegistry,
+  type WebhookRegistry,
+  type WebhookRegistration,
+} from '@/webhooks/index.js';
 
 export const pluginTypes = ['core', 'source', 'other'] as const;
 
@@ -202,6 +207,11 @@ export interface LoadConfigFileOptions {
   store?: NodeStore;
   /** Context to pass to registerTypes hook (from SchemaRegistry) */
   registerTypesContext?: RegisterTypesContext;
+  /**
+   * Webhook registry for plugins to register webhook handlers.
+   * If not provided, uses the defaultWebhookRegistry singleton.
+   */
+  webhookRegistry?: WebhookRegistry;
 }
 
 /**
@@ -231,12 +241,19 @@ export async function loadConfigFile(
     // Execute sourceNodes hook with node actions bound to this plugin
     if (module.sourceNodes && options?.pluginName && options?.store) {
       const actions = createNodeActions(options.store, options.pluginName);
+      const webhookRegistry = options.webhookRegistry ?? defaultWebhookRegistry;
+
+      // Create a bound registerWebhook function for this plugin
+      const registerWebhook = (webhook: WebhookRegistration): void => {
+        webhookRegistry.register(options.pluginName!, webhook);
+      };
 
       await module.sourceNodes({
         actions,
         createNodeId,
         createContentDigest,
         options: options.context?.options,
+        registerWebhook,
       });
     }
 
@@ -356,6 +373,11 @@ export interface LoadPluginsOptions {
    * Each plugin will store its cache in `cacheDir/.udl-cache/`.
    */
   cacheDir?: string;
+  /**
+   * Webhook registry for plugins to register webhook handlers.
+   * If not provided, uses the defaultWebhookRegistry singleton.
+   */
+  webhookRegistry?: WebhookRegistry;
 }
 
 /** Maximum recursion depth for nested plugins */
@@ -484,6 +506,7 @@ export async function loadPlugins(
     _depth = 0,
     cache: cacheEnabled = true,
     cacheDir,
+    webhookRegistry = defaultWebhookRegistry,
   } = options ?? {};
   const nodeStore = store ?? defaultStore;
   const codegenConfigs: PluginCodegenInfo[] = [];
@@ -592,12 +615,19 @@ export async function loadPlugins(
           }
 
           const actions = createNodeActions(nodeStore, actualPluginName);
+
+          // Create a bound registerWebhook function for this plugin
+          const registerWebhook = (webhook: WebhookRegistration): void => {
+            webhookRegistry.register(actualPluginName, webhook);
+          };
+
           await module.sourceNodes({
             actions,
             createNodeId,
             createContentDigest,
             options: context?.options,
             cacheDir: cacheLocation,
+            registerWebhook,
           });
 
           registerPluginIndexes(nodeStore, actualPluginName, allIndexes);
@@ -672,6 +702,7 @@ export async function loadPlugins(
             cache: cacheEnabled,
             // Nested plugins store their cache in the parent plugin's directory
             cacheDir: pluginPath,
+            webhookRegistry,
           });
 
           codegenConfigs.push(...nestedResult.codegenConfigs);
diff --git a/packages/core/src/nodes/index.ts b/packages/core/src/nodes/index.ts
index 8059b73..bea4d29 100644
--- a/packages/core/src/nodes/index.ts
+++ b/packages/core/src/nodes/index.ts
@@ -39,6 +39,7 @@ export { createNodeId, createContentDigest } from './utils/index.js';
 
 // Context for sourceNodes hook
 import type { NodeActions } from './actions/index.js';
+import type { WebhookRegistration } from '@/webhooks/types.js';
 
 /**
  * Context passed to the sourceNodes lifecycle hook
@@ -59,4 +60,22 @@ export interface SourceNodesContext<T = Record<string, unknown>> {
    * This is the directory containing the udl.config.ts that loaded this plugin.
    */
   cacheDir?: string;
+  /**
+   * Register a webhook handler for this plugin.
+   * The webhook will be available at `/_webhooks/{pluginName}/{path}`.
+   *
+   * @example
+   * ```typescript
+   * registerWebhook({
+   *   path: 'entry-update',
+   *   handler: async (req, res, context) => {
+   *     const { body, actions } = context;
+   *     await actions.createNode(transformEntry(body), { ... });
+   *     res.writeHead(200);
+   *     res.end();
+   *   },
+   * });
+   * ```
+   */
+  registerWebhook: (webhook: WebhookRegistration) => void;
 }
diff --git a/packages/core/src/webhooks/index.ts b/packages/core/src/webhooks/index.ts
new file mode 100644
index 0000000..b990a22
--- /dev/null
+++ b/packages/core/src/webhooks/index.ts
@@ -0,0 +1,23 @@
+/**
+ * Webhook system for plugin webhook registration.
+ *
+ * This module provides the infrastructure for plugins to register webhook
+ * handlers that receive and process incoming webhook payloads from external
+ * data sources like Contentful, Shopify, etc.
+ */
+
+// Types
+export type {
+  WebhookRegistration,
+  WebhookHandlerFn,
+  WebhookHandlerContext,
+  WebhookHandler,
+} from './types.js';
+
+// Registry
+export {
+  WebhookRegistry,
+  WebhookRegistrationError,
+  defaultWebhookRegistry,
+  setDefaultWebhookRegistry,
+} from './registry.js';
diff --git a/packages/core/src/webhooks/registry.ts b/packages/core/src/webhooks/registry.ts
new file mode 100644
index 0000000..9e13f4c
--- /dev/null
+++ b/packages/core/src/webhooks/registry.ts
@@ -0,0 +1,263 @@
+/**
+ * Webhook Registry
+ *
+ * Central registry for webhook handlers from all plugins.
+ * Stores registered webhooks and provides lookup for routing
+ * incoming webhook requests to the appropriate handler.
+ */
+
+import type { WebhookRegistration, WebhookHandler } from './types.js';
+
+/**
+ * Regular expression for validating webhook paths.
+ * Paths must:
+ * - Not start with a slash
+ * - Contain only alphanumeric characters, hyphens, and underscores
+ * - Not be empty
+ */
+const PATH_REGEX = /^[a-zA-Z0-9][a-zA-Z0-9_-]*$/;
+
+/**
+ * Error thrown when webhook registration fails validation.
+ */
+export class WebhookRegistrationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'WebhookRegistrationError';
+  }
+}
+
+/**
+ * Central registry for webhook handlers.
+ *
+ * Plugins register their webhook handlers and the registry
+ * provides lookup for routing incoming requests.
+ *
+ * @example
+ * ```typescript
+ * const registry = new WebhookRegistry();
+ *
+ * // Register a webhook
+ * registry.register('my-plugin', {
+ *   path: 'entry-update',
+ *   handler: async (req, res, context) => { ... },
+ * });
+ *
+ * // Look up a handler
+ * const handler = registry.getHandler('my-plugin', 'entry-update');
+ * ```
+ */
+export class WebhookRegistry {
+  private handlers: Map<string, WebhookHandler> = new Map();
+
+  /**
+   * Generate the map key for a webhook handler.
+   * @param pluginName - The plugin that registered the webhook
+   * @param path - The webhook path
+   * @returns The map key in format "pluginName/path"
+   */
+  private getKey(pluginName: string, path: string): string {
+    return `${pluginName}/${path}`;
+  }
+
+  /**
+   * Validate a webhook path.
+   * @param path - The path to validate
+   * @throws {WebhookRegistrationError} If the path is invalid
+   */
+  private validatePath(path: string): void {
+    if (!path) {
+      throw new WebhookRegistrationError('Webhook path cannot be empty');
+    }
+
+    if (path.startsWith('/')) {
+      throw new WebhookRegistrationError(
+        `Webhook path cannot start with '/': ${path}`
+      );
+    }
+
+    if (!PATH_REGEX.test(path)) {
+      throw new WebhookRegistrationError(
+        `Webhook path contains invalid characters: ${path}. ` +
+          'Path must contain only alphanumeric characters, hyphens, and underscores, ' +
+          'and must start with an alphanumeric character.'
+      );
+    }
+  }
+
+  /**
+   * Register a webhook handler for a plugin.
+   *
+   * @param pluginName - The name of the plugin registering the webhook
+   * @param webhook - The webhook registration configuration
+   * @throws {WebhookRegistrationError} If the path is invalid or already registered
+   *
+   * @example
+   * ```typescript
+   * registry.register('@my-org/plugin-source-cms', {
+   *   path: 'content-update',
+   *   handler: async (req, res, context) => {
+   *     // Handle webhook
+   *   },
+   *   verifySignature: (req, body) => verifyHmac(body, req.headers['x-signature']),
+   *   description: 'Handles content update events',
+   * });
+   * ```
+   */
+  register(pluginName: string, webhook: WebhookRegistration): void {
+    this.validatePath(webhook.path);
+
+    const key = this.getKey(pluginName, webhook.path);
+
+    if (this.handlers.has(key)) {
+      throw new WebhookRegistrationError(
+        `Webhook path '${webhook.path}' is already registered for plugin '${pluginName}'`
+      );
+    }
+
+    const handler: WebhookHandler = {
+      ...webhook,
+      pluginName,
+    };
+
+    this.handlers.set(key, handler);
+  }
+
+  /**
+   * Get a webhook handler by plugin name and path.
+   *
+   * @param pluginName - The plugin that registered the webhook
+   * @param path - The webhook path
+   * @returns The webhook handler, or undefined if not found
+   *
+   * @example
+   * ```typescript
+   * const handler = registry.getHandler('my-plugin', 'entry-update');
+   * if (handler) {
+   *   await handler.handler(req, res, context);
+   * }
+   * ```
+   */
+  getHandler(pluginName: string, path: string): WebhookHandler | undefined {
+    const key = this.getKey(pluginName, path);
+    return this.handlers.get(key);
+  }
+
+  /**
+   * Check if a webhook handler exists.
+   *
+   * @param pluginName - The plugin name
+   * @param path - The webhook path
+   * @returns True if the handler exists
+   */
+  has(pluginName: string, path: string): boolean {
+    const key = this.getKey(pluginName, path);
+    return this.handlers.has(key);
+  }
+
+  /**
+   * Get all registered webhook handlers.
+   *
+   * @returns Array of all registered webhook handlers
+   *
+   * @example
+   * ```typescript
+   * const allHandlers = registry.getAllHandlers();
+   * console.log(`${allHandlers.length} webhooks registered`);
+   * ```
+   */
+  getAllHandlers(): WebhookHandler[] {
+    return Array.from(this.handlers.values());
+  }
+
+  /**
+   * Get all webhook handlers registered by a specific plugin.
+   *
+   * @param pluginName - The plugin name to filter by
+   * @returns Array of webhook handlers for the specified plugin
+   *
+   * @example
+   * ```typescript
+   * const contentfulWebhooks = registry.getHandlersByPlugin(
+   *   '@universal-data-layer/plugin-source-contentful'
+   * );
+   * ```
+   */
+  getHandlersByPlugin(pluginName: string): WebhookHandler[] {
+    return Array.from(this.handlers.values()).filter(
+      (handler) => handler.pluginName === pluginName
+    );
+  }
+
+  /**
+   * Remove a webhook handler.
+   *
+   * @param pluginName - The plugin name
+   * @param path - The webhook path
+   * @returns True if a handler was removed, false if it didn't exist
+   */
+  unregister(pluginName: string, path: string): boolean {
+    const key = this.getKey(pluginName, path);
+    return this.handlers.delete(key);
+  }
+
+  /**
+   * Clear all registered webhook handlers.
+   * Useful for testing to ensure isolation between test runs.
+   *
+   * @example
+   * ```typescript
+   * beforeEach(() => {
+   *   webhookRegistry.clear();
+   * });
+   * ```
+   */
+  clear(): void {
+    this.handlers.clear();
+  }
+
+  /**
+   * Get the number of registered webhook handlers.
+   *
+   * @returns The count of registered handlers
+   */
+  size(): number {
+    return this.handlers.size;
+  }
+}
+
+/**
+ * Default singleton webhook registry instance.
+ *
+ * This is automatically created on first import and persists across the application.
+ * All plugins using the default behavior will share this registry.
+ *
+ * @example
+ * ```typescript
+ * import { defaultWebhookRegistry } from 'universal-data-layer';
+ *
+ * // Check registered webhooks
+ * const handlers = defaultWebhookRegistry.getAllHandlers();
+ * console.log(`${handlers.length} webhook handlers registered`);
+ * ```
+ */
+export let defaultWebhookRegistry: WebhookRegistry = new WebhookRegistry();
+
+/**
+ * Replace the default webhook registry with a new instance.
+ * Useful for testing to ensure isolation between test runs.
+ *
+ * @param registry - The new registry to use as the default
+ *
+ * @example
+ * ```typescript
+ * import { setDefaultWebhookRegistry, WebhookRegistry } from 'universal-data-layer';
+ *
+ * beforeEach(() => {
+ *   setDefaultWebhookRegistry(new WebhookRegistry());
+ * });
+ * ```
+ */
+export function setDefaultWebhookRegistry(registry: WebhookRegistry): void {
+  defaultWebhookRegistry = registry;
+}
diff --git a/packages/core/src/webhooks/types.ts b/packages/core/src/webhooks/types.ts
new file mode 100644
index 0000000..51d8980
--- /dev/null
+++ b/packages/core/src/webhooks/types.ts
@@ -0,0 +1,124 @@
+/**
+ * Webhook system types for plugin webhook registration.
+ *
+ * These interfaces allow plugins to register webhook handlers that will
+ * receive and process incoming webhook payloads from external data sources.
+ */
+
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { NodeStore } from '@/nodes/store.js';
+import type { NodeActions } from '@/nodes/actions/index.js';
+
+/**
+ * Context passed to webhook handlers when processing incoming requests.
+ *
+ * @example
+ * ```typescript
+ * handler: async (req, res, context) => {
+ *   const { body, actions } = context;
+ *   if (body.type === 'entry.publish') {
+ *     await actions.createNode(transformEntry(body.entry), { ... });
+ *   }
+ *   res.writeHead(200);
+ *   res.end();
+ * }
+ * ```
+ */
+export interface WebhookHandlerContext {
+  /** Access to the node store for querying existing nodes */
+  store: NodeStore;
+  /** Bound node actions for creating, updating, or deleting nodes */
+  actions: NodeActions;
+  /** Raw body buffer for signature verification */
+  rawBody: Buffer;
+  /** Parsed JSON body (if content-type is application/json), otherwise undefined */
+  body: unknown;
+}
+
+/**
+ * Function signature for webhook handlers.
+ *
+ * Handlers receive the raw HTTP request and response objects along with
+ * a context containing node store access and parsed body data.
+ */
+export type WebhookHandlerFn = (
+  req: IncomingMessage,
+  res: ServerResponse,
+  context: WebhookHandlerContext
+) => Promise<void>;
+
+/**
+ * Configuration for registering a webhook handler.
+ *
+ * Plugins provide this configuration when calling `registerWebhook()` in
+ * their `sourceNodes` hook. The path is combined with the plugin name to
+ * create the full webhook URL.
+ *
+ * @example
+ * ```typescript
+ * // In plugin's sourceNodes hook
+ * registerWebhook({
+ *   path: 'entry-update',
+ *   description: 'Handles Contentful entry publish/unpublish events',
+ *   handler: async (req, res, context) => {
+ *     const { body, actions } = context;
+ *     // Process webhook payload and update nodes
+ *     await actions.createNode(transformEntry(body), { ... });
+ *     res.writeHead(200, { 'Content-Type': 'application/json' });
+ *     res.end(JSON.stringify({ received: true }));
+ *   },
+ *   verifySignature: (req, body) => {
+ *     const signature = req.headers['x-contentful-signature'];
+ *     return verifyHmac(body, signature, secret);
+ *   },
+ * });
+ * ```
+ */
+export interface WebhookRegistration {
+  /**
+   * Path suffix for the webhook endpoint.
+   * Combined with plugin name to form full path: `/_webhooks/{pluginName}/{path}`
+   *
+   * Must not start with `/` and can only contain alphanumeric characters,
+   * hyphens, and underscores.
+   *
+   * @example 'entry-update'
+   * @example 'product_sync'
+   */
+  path: string;
+
+  /**
+   * Handler function to process incoming webhook payloads.
+   * Receives raw request/response objects and a context with node store access.
+   */
+  handler: WebhookHandlerFn;
+
+  /**
+   * Optional function to verify webhook signatures.
+   * Called before the handler to validate the request authenticity.
+   * Return `true` if signature is valid, `false` to reject the request.
+   *
+   * @param req - The incoming HTTP request with headers
+   * @param body - Raw body buffer for computing signatures
+   * @returns Whether the signature is valid
+   */
+  verifySignature?: (
+    req: IncomingMessage,
+    body: Buffer
+  ) => boolean | Promise<boolean>;
+
+  /**
+   * Optional description for logging and debugging purposes.
+   * @example 'Handles Contentful entry publish/unpublish events'
+   */
+  description?: string;
+}
+
+/**
+ * Internal representation of a registered webhook handler.
+ * Includes the plugin name that registered it for routing purposes.
+ */
+export interface WebhookHandler extends WebhookRegistration {
+  /** Name of the plugin that registered this webhook */
+  pluginName: string;
+}
diff --git a/packages/core/tests/unit/webhooks/registry.test.ts b/packages/core/tests/unit/webhooks/registry.test.ts
new file mode 100644
index 0000000..ab5a658
--- /dev/null
+++ b/packages/core/tests/unit/webhooks/registry.test.ts
@@ -0,0 +1,334 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import {
+  WebhookRegistry,
+  WebhookRegistrationError,
+  setDefaultWebhookRegistry,
+  defaultWebhookRegistry,
+  type WebhookRegistration,
+  type WebhookHandlerContext,
+} from '@/webhooks/index.js';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+
+// Sample webhook handler for testing
+const createTestWebhook = (
+  path: string,
+  description?: string
+): WebhookRegistration => {
+  const webhook: WebhookRegistration = {
+    path,
+    handler: async (
+      _req: IncomingMessage,
+      res: ServerResponse,
+      _context: WebhookHandlerContext
+    ) => {
+      res.writeHead(200);
+      res.end('OK');
+    },
+  };
+  if (description !== undefined) {
+    webhook.description = description;
+  }
+  return webhook;
+};
+
+// Sample webhook with signature verification
+const createWebhookWithSignature = (path: string): WebhookRegistration => ({
+  path,
+  handler: async (
+    _req: IncomingMessage,
+    res: ServerResponse,
+    _context: WebhookHandlerContext
+  ) => {
+    res.writeHead(200);
+    res.end('OK');
+  },
+  verifySignature: (_req: IncomingMessage, _body: Buffer) => {
+    return true;
+  },
+});
+
+describe('WebhookRegistry', () => {
+  let registry: WebhookRegistry;
+
+  beforeEach(() => {
+    registry = new WebhookRegistry();
+  });
+
+  describe('register', () => {
+    it('should register a webhook handler', () => {
+      const webhook = createTestWebhook('entry-update', 'Handle entry updates');
+
+      registry.register('test-plugin', webhook);
+
+      const handler = registry.getHandler('test-plugin', 'entry-update');
+      expect(handler).toBeDefined();
+      expect(handler?.path).toBe('entry-update');
+      expect(handler?.pluginName).toBe('test-plugin');
+      expect(handler?.description).toBe('Handle entry updates');
+    });
+
+    it('should preserve the handler function', () => {
+      const webhook = createTestWebhook('test-path');
+
+      registry.register('test-plugin', webhook);
+
+      const handler = registry.getHandler('test-plugin', 'test-path');
+      expect(handler?.handler).toBe(webhook.handler);
+    });
+
+    it('should preserve optional verifySignature function', () => {
+      const webhook = createWebhookWithSignature('signed-webhook');
+
+      registry.register('test-plugin', webhook);
+
+      const handler = registry.getHandler('test-plugin', 'signed-webhook');
+      expect(handler?.verifySignature).toBe(webhook.verifySignature);
+    });
+
+    it('should allow same path for different plugins', () => {
+      const webhook1 = createTestWebhook('update');
+      const webhook2 = createTestWebhook('update');
+
+      registry.register('plugin-a', webhook1);
+      registry.register('plugin-b', webhook2);
+
+      expect(registry.getHandler('plugin-a', 'update')).toBeDefined();
+      expect(registry.getHandler('plugin-b', 'update')).toBeDefined();
+      expect(registry.size()).toBe(2);
+    });
+
+    it('should throw error for duplicate path within same plugin', () => {
+      const webhook1 = createTestWebhook('duplicate');
+      const webhook2 = createTestWebhook('duplicate');
+
+      registry.register('test-plugin', webhook1);
+
+      expect(() => registry.register('test-plugin', webhook2)).toThrow(
+        WebhookRegistrationError
+      );
+      expect(() => registry.register('test-plugin', webhook2)).toThrow(
+        "Webhook path 'duplicate' is already registered for plugin 'test-plugin'"
+      );
+    });
+  });
+
+  describe('path validation', () => {
+    it('should accept valid paths with alphanumeric characters', () => {
+      expect(() =>
+        registry.register('test', createTestWebhook('valid123'))
+      ).not.toThrow();
+    });
+
+    it('should accept valid paths with hyphens', () => {
+      expect(() =>
+        registry.register('test', createTestWebhook('entry-update'))
+      ).not.toThrow();
+    });
+
+    it('should accept valid paths with underscores', () => {
+      expect(() =>
+        registry.register('test', createTestWebhook('entry_update'))
+      ).not.toThrow();
+    });
+
+    it('should accept valid paths with mixed characters', () => {
+      expect(() =>
+        registry.register('test', createTestWebhook('v1-entry_update'))
+      ).not.toThrow();
+    });
+
+    it('should reject empty paths', () => {
+      expect(() => registry.register('test', createTestWebhook(''))).toThrow(
+        WebhookRegistrationError
+      );
+      expect(() => registry.register('test', createTestWebhook(''))).toThrow(
+        'Webhook path cannot be empty'
+      );
+    });
+
+    it('should reject paths starting with slash', () => {
+      expect(() =>
+        registry.register('test', createTestWebhook('/entry-update'))
+      ).toThrow(WebhookRegistrationError);
+      expect(() =>
+        registry.register('test', createTestWebhook('/entry-update'))
+      ).toThrow("Webhook path cannot start with '/'");
+    });
+
+    it('should reject paths with invalid characters', () => {
+      expect(() =>
+        registry.register('test', createTestWebhook('entry.update'))
+      ).toThrow(WebhookRegistrationError);
+      expect(() =>
+        registry.register('test', createTestWebhook('entry@update'))
+      ).toThrow(WebhookRegistrationError);
+      expect(() =>
+        registry.register('test', createTestWebhook('entry update'))
+      ).toThrow(WebhookRegistrationError);
+    });
+
+    it('should reject paths starting with hyphen', () => {
+      expect(() =>
+        registry.register('test', createTestWebhook('-entry'))
+      ).toThrow(WebhookRegistrationError);
+    });
+
+    it('should reject paths starting with underscore', () => {
+      expect(() =>
+        registry.register('test', createTestWebhook('_entry'))
+      ).toThrow(WebhookRegistrationError);
+    });
+  });
+
+  describe('getHandler', () => {
+    it('should return handler for existing plugin+path', () => {
+      registry.register('my-plugin', createTestWebhook('webhook-path'));
+
+      const handler = registry.getHandler('my-plugin', 'webhook-path');
+      expect(handler).toBeDefined();
+      expect(handler?.pluginName).toBe('my-plugin');
+    });
+
+    it('should return undefined for non-existent handler', () => {
+      expect(registry.getHandler('non-existent', 'path')).toBeUndefined();
+    });
+
+    it('should return undefined for wrong plugin name', () => {
+      registry.register('plugin-a', createTestWebhook('path'));
+
+      expect(registry.getHandler('plugin-b', 'path')).toBeUndefined();
+    });
+
+    it('should return undefined for wrong path', () => {
+      registry.register('plugin', createTestWebhook('path-a'));
+
+      expect(registry.getHandler('plugin', 'path-b')).toBeUndefined();
+    });
+  });
+
+  describe('has', () => {
+    it('should return true for existing handler', () => {
+      registry.register('plugin', createTestWebhook('path'));
+
+      expect(registry.has('plugin', 'path')).toBe(true);
+    });
+
+    it('should return false for non-existent handler', () => {
+      expect(registry.has('plugin', 'path')).toBe(false);
+    });
+  });
+
+  describe('getAllHandlers', () => {
+    it('should return empty array when no handlers registered', () => {
+      expect(registry.getAllHandlers()).toEqual([]);
+    });
+
+    it('should return all registered handlers', () => {
+      registry.register('plugin-a', createTestWebhook('path-1'));
+      registry.register('plugin-a', createTestWebhook('path-2'));
+      registry.register('plugin-b', createTestWebhook('path-1'));
+
+      const handlers = registry.getAllHandlers();
+      expect(handlers).toHaveLength(3);
+    });
+
+    it('should include pluginName in returned handlers', () => {
+      registry.register('my-plugin', createTestWebhook('my-path'));
+
+      const handlers = registry.getAllHandlers();
+      expect(handlers[0]?.pluginName).toBe('my-plugin');
+      expect(handlers[0]?.path).toBe('my-path');
+    });
+  });
+
+  describe('getHandlersByPlugin', () => {
+    beforeEach(() => {
+      registry.register('plugin-a', createTestWebhook('path-1'));
+      registry.register('plugin-a', createTestWebhook('path-2'));
+      registry.register('plugin-b', createTestWebhook('path-3'));
+    });
+
+    it('should return only handlers for specified plugin', () => {
+      const handlers = registry.getHandlersByPlugin('plugin-a');
+
+      expect(handlers).toHaveLength(2);
+      expect(handlers.every((h) => h.pluginName === 'plugin-a')).toBe(true);
+    });
+
+    it('should return empty array for plugin with no handlers', () => {
+      const handlers = registry.getHandlersByPlugin('non-existent');
+
+      expect(handlers).toEqual([]);
+    });
+  });
+
+  describe('unregister', () => {
+    it('should remove a registered handler', () => {
+      registry.register('plugin', createTestWebhook('path'));
+
+      const result = registry.unregister('plugin', 'path');
+
+      expect(result).toBe(true);
+      expect(registry.getHandler('plugin', 'path')).toBeUndefined();
+    });
+
+    it('should return false when handler does not exist', () => {
+      const result = registry.unregister('non-existent', 'path');
+
+      expect(result).toBe(false);
+    });
+  });
+
+  describe('clear', () => {
+    it('should remove all handlers', () => {
+      registry.register('plugin-a', createTestWebhook('path-1'));
+      registry.register('plugin-b', createTestWebhook('path-2'));
+
+      registry.clear();
+
+      expect(registry.getAllHandlers()).toEqual([]);
+      expect(registry.size()).toBe(0);
+    });
+  });
+
+  describe('size', () => {
+    it('should return 0 for empty registry', () => {
+      expect(registry.size()).toBe(0);
+    });
+
+    it('should return correct count after registrations', () => {
+      registry.register('plugin', createTestWebhook('path-1'));
+      registry.register('plugin', createTestWebhook('path-2'));
+
+      expect(registry.size()).toBe(2);
+    });
+
+    it('should update after unregister', () => {
+      registry.register('plugin', createTestWebhook('path'));
+      expect(registry.size()).toBe(1);
+
+      registry.unregister('plugin', 'path');
+      expect(registry.size()).toBe(0);
+    });
+  });
+});
+
+describe('defaultWebhookRegistry singleton', () => {
+  beforeEach(() => {
+    // Reset to a fresh registry before each test
+    setDefaultWebhookRegistry(new WebhookRegistry());
+  });
+
+  it('should be a WebhookRegistry instance', () => {
+    expect(defaultWebhookRegistry).toBeInstanceOf(WebhookRegistry);
+  });
+
+  it('should be replaceable via setDefaultWebhookRegistry', () => {
+    const newRegistry = new WebhookRegistry();
+    newRegistry.register('test', createTestWebhook('test-path'));
+
+    setDefaultWebhookRegistry(newRegistry);
+
+    expect(defaultWebhookRegistry.has('test', 'test-path')).toBe(true);
+  });
+});

From f792c59860e0dbd5128a66020f6bd42a69d52984 Mon Sep 17 00:00:00 2001
From: dawidurbanski <hi@dawidurbanski.com>
Date: Sun, 21 Dec 2025 20:36:10 +0100
Subject: [PATCH 05/46] feat(core): add webhook HTTP routing

Add HTTP routing for incoming webhooks at POST /_webhooks/:plugin/:path.
Routes webhook payloads to the correct plugin handler registered via
the webhook registry.

Features:
- Route webhooks based on plugin name and path from URL
- Validate HTTP method (only POST allowed, returns 405 otherwise)
- Collect raw request body for signature verification
- Parse JSON body when content-type is application/json
- Provide WebhookHandlerContext with store, actions, rawBody, and body
- Enforce 1MB body size limit to prevent abuse (returns 413)
- Return appropriate HTTP status codes (405, 404, 401, 400, 500)
- Log webhook activity for debugging

Closes #61
---
 .changeset/add-webhook-http-routing.md        |  36 +
 packages/core/src/handlers/webhook.ts         | 202 ++++++
 packages/core/src/server.ts                   |   6 +
 .../tests/integration/webhook-routing.test.ts | 447 ++++++++++++
 .../core/tests/unit/handlers/webhook.test.ts  | 681 ++++++++++++++++++
 5 files changed, 1372 insertions(+)
 create mode 100644 .changeset/add-webhook-http-routing.md
 create mode 100644 packages/core/src/handlers/webhook.ts
 create mode 100644 packages/core/tests/integration/webhook-routing.test.ts
 create mode 100644 packages/core/tests/unit/handlers/webhook.test.ts

diff --git a/.changeset/add-webhook-http-routing.md b/.changeset/add-webhook-http-routing.md
new file mode 100644
index 0000000..854ea6c
--- /dev/null
+++ b/.changeset/add-webhook-http-routing.md
@@ -0,0 +1,36 @@
+---
+'universal-data-layer': minor
+---
+
+Add webhook HTTP routing for incoming webhooks
+
+Routes incoming webhook requests to the appropriate plugin handler based on the URL path `POST /_webhooks/{pluginName}/{path}`.
+
+**Features:**
+
+- Routes webhooks to correct handler based on plugin name and path
+- Validates HTTP method (only POST allowed)
+- Collects raw request body for signature verification
+- Parses JSON body when content-type is `application/json`
+- Provides `WebhookHandlerContext` with store, actions, rawBody, and body
+- Enforces 1MB body size limit to prevent abuse
+- Returns appropriate HTTP status codes (405, 404, 401, 400, 500)
+- Logs webhook activity for debugging
+
+**URL Format:**
+
+```
+POST /_webhooks/{plugin-name}/{webhook-path}
+
+Examples:
+POST /_webhooks/contentful/entry-update
+POST /_webhooks/shopify/product-update
+POST /_webhooks/custom-plugin/sync
+```
+
+**New exports:**
+
+- `isWebhookRequest` - Check if URL is a webhook request
+- `parseWebhookUrl` - Parse plugin name and path from URL
+- `webhookHandler` - HTTP handler for webhook requests
+- `WEBHOOK_PATH_PREFIX` - URL prefix constant (`/_webhooks/`)
diff --git a/packages/core/src/handlers/webhook.ts b/packages/core/src/handlers/webhook.ts
new file mode 100644
index 0000000..4aea563
--- /dev/null
+++ b/packages/core/src/handlers/webhook.ts
@@ -0,0 +1,202 @@
+/**
+ * Webhook HTTP Handler
+ *
+ * Routes incoming webhook requests to the appropriate plugin handler.
+ * URL format: POST /_webhooks/{pluginName}/{path}
+ */
+
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { defaultWebhookRegistry } from '@/webhooks/index.js';
+import { defaultStore } from '@/nodes/defaultStore.js';
+import { createNodeActions } from '@/nodes/actions/index.js';
+import type { WebhookHandlerContext } from '@/webhooks/index.js';
+
+/** URL path prefix for webhook endpoints */
+export const WEBHOOK_PATH_PREFIX = '/_webhooks/';
+
+/** Maximum request body size (1MB) */
+const MAX_BODY_SIZE = 1024 * 1024;
+
+/**
+ * Check if a URL is a webhook request.
+ *
+ * @param url - The request URL to check
+ * @returns True if the URL starts with the webhook path prefix
+ */
+export function isWebhookRequest(url: string): boolean {
+  return url.startsWith(WEBHOOK_PATH_PREFIX);
+}
+
+/**
+ * Parse the webhook URL to extract plugin name and path.
+ *
+ * @param url - The full request URL (e.g., "/_webhooks/contentful/entry-update")
+ * @returns Object with pluginName and webhookPath, or null if invalid
+ */
+export function parseWebhookUrl(
+  url: string
+): { pluginName: string; webhookPath: string } | null {
+  if (!isWebhookRequest(url)) {
+    return null;
+  }
+
+  // Remove prefix and any query string
+  const urlPath = url.slice(WEBHOOK_PATH_PREFIX.length);
+  const pathWithoutPrefix = urlPath.split('?')[0] ?? urlPath;
+  const parts = pathWithoutPrefix.split('/');
+
+  // Need at least plugin name and one path segment
+  if (parts.length < 2 || !parts[0] || !parts[1]) {
+    return null;
+  }
+
+  return {
+    pluginName: parts[0],
+    webhookPath: parts.slice(1).join('/'),
+  };
+}
+
+/**
+ * Collect the request body as a Buffer.
+ *
+ * @param req - The incoming HTTP request
+ * @returns Promise resolving to the body Buffer
+ * @throws Error if body exceeds MAX_BODY_SIZE
+ */
+export async function collectRequestBody(
+  req: IncomingMessage
+): Promise<Buffer> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    let totalSize = 0;
+
+    req.on('data', (chunk: Buffer) => {
+      totalSize += chunk.length;
+      if (totalSize > MAX_BODY_SIZE) {
+        req.destroy();
+        reject(new Error('Request body too large'));
+        return;
+      }
+      chunks.push(chunk);
+    });
+
+    req.on('end', () => {
+      resolve(Buffer.concat(chunks));
+    });
+
+    req.on('error', reject);
+  });
+}
+
+/**
+ * Main webhook HTTP handler.
+ *
+ * Routes incoming webhook requests to the appropriate plugin handler
+ * based on the URL path.
+ *
+ * @param req - The incoming HTTP request
+ * @param res - The server response
+ */
+export async function webhookHandler(
+  req: IncomingMessage,
+  res: ServerResponse
+): Promise<void> {
+  // Only accept POST requests
+  if (req.method !== 'POST') {
+    res.writeHead(405, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: 'Method not allowed' }));
+    return;
+  }
+
+  // Parse the URL to get plugin name and path
+  const parsed = parseWebhookUrl(req.url || '');
+  if (!parsed) {
+    res.writeHead(404, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: 'Invalid webhook URL format' }));
+    return;
+  }
+
+  const { pluginName, webhookPath } = parsed;
+
+  // Look up the registered handler
+  const handler = defaultWebhookRegistry.getHandler(pluginName, webhookPath);
+  if (!handler) {
+    res.writeHead(404, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: 'Webhook handler not found' }));
+    return;
+  }
+
+  // Collect request body
+  let rawBody: Buffer;
+  try {
+    rawBody = await collectRequestBody(req);
+  } catch (error) {
+    if (error instanceof Error && error.message === 'Request body too large') {
+      res.writeHead(413, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: 'Payload too large' }));
+      return;
+    }
+    res.writeHead(400, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: 'Failed to read request body' }));
+    return;
+  }
+
+  // Verify signature if handler requires it
+  if (handler.verifySignature) {
+    try {
+      const isValid = await handler.verifySignature(req, rawBody);
+      if (!isValid) {
+        console.warn(
+          `Webhook signature verification failed: ${pluginName}/${webhookPath}`
+        );
+        res.writeHead(401, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Invalid signature' }));
+        return;
+      }
+    } catch (error) {
+      console.error(
+        `Webhook signature verification error: ${pluginName}/${webhookPath}`,
+        error
+      );
+      res.writeHead(401, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: 'Signature verification failed' }));
+      return;
+    }
+  }
+
+  // Parse JSON body if content-type indicates JSON
+  let body: unknown = undefined;
+  const contentType = req.headers['content-type'] || '';
+  if (contentType.includes('application/json')) {
+    try {
+      body = JSON.parse(rawBody.toString('utf-8'));
+    } catch {
+      res.writeHead(400, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: 'Invalid JSON body' }));
+      return;
+    }
+  }
+
+  // Create context for the handler
+  const actions = createNodeActions(defaultStore, pluginName);
+  const context: WebhookHandlerContext = {
+    store: defaultStore,
+    actions,
+    rawBody,
+    body,
+  };
+
+  console.log(`Webhook received: ${pluginName}/${webhookPath}`);
+
+  // Call the handler
+  try {
+    await handler.handler(req, res, context);
+  } catch (error) {
+    console.error(`Webhook handler error: ${pluginName}/${webhookPath}`, error);
+    // Only send error response if headers haven't been sent
+    if (!res.headersSent) {
+      res.writeHead(500, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: 'Internal server error' }));
+    }
+  }
+}
diff --git a/packages/core/src/server.ts b/packages/core/src/server.ts
index 240260d..f24fe40 100644
--- a/packages/core/src/server.ts
+++ b/packages/core/src/server.ts
@@ -3,6 +3,7 @@ import staticHandler from '@/handlers/static.js';
 import graphqlHandler from '@/handlers/graphql.js';
 import graphiqlHandler from '@/handlers/graphiql.js';
 import { healthHandler, readyHandler } from '@/handlers/health.js';
+import { isWebhookRequest, webhookHandler } from '@/handlers/webhook.js';
 
 const server = createServer((req, res) => {
   // Add CORS headers for all requests
@@ -24,6 +25,11 @@ const server = createServer((req, res) => {
     return readyHandler(req, res);
   }
 
+  // Webhook endpoints
+  if (req.url && isWebhookRequest(req.url)) {
+    return webhookHandler(req, res);
+  }
+
   if (req.url === '/graphql') {
     return graphqlHandler(req, res);
   } else if (req.url === '/graphiql') {
diff --git a/packages/core/tests/integration/webhook-routing.test.ts b/packages/core/tests/integration/webhook-routing.test.ts
new file mode 100644
index 0000000..68341ce
--- /dev/null
+++ b/packages/core/tests/integration/webhook-routing.test.ts
@@ -0,0 +1,447 @@
+import { describe, it, expect, beforeAll, afterAll, beforeEach } from 'vitest';
+import http, {
+  createServer,
+  type Server,
+  type IncomingMessage,
+} from 'node:http';
+import { isWebhookRequest, webhookHandler } from '@/handlers/webhook.js';
+import {
+  WebhookRegistry,
+  setDefaultWebhookRegistry,
+  type WebhookRegistration,
+  type WebhookHandlerContext,
+} from '@/webhooks/index.js';
+import { NodeStore } from '@/nodes/store.js';
+import { setDefaultStore } from '@/nodes/defaultStore.js';
+
+function makeRequest(
+  server: Server,
+  path: string,
+  options: {
+    method?: string;
+    body?: string;
+    headers?: Record<string, string>;
+  } = {}
+): Promise<{
+  statusCode: number;
+  headers: Record<string, string>;
+  body: string;
+}> {
+  return new Promise((resolve, reject) => {
+    const address = server.address();
+    if (!address || typeof address === 'string') {
+      reject(new Error('Server address not available'));
+      return;
+    }
+
+    const { method = 'POST', body, headers = {} } = options;
+
+    const req = http.request(
+      {
+        hostname: 'localhost',
+        port: address.port,
+        path,
+        method,
+        headers: {
+          'Content-Type': 'application/json',
+          ...headers,
+        },
+      },
+      (res: IncomingMessage) => {
+        let responseBody = '';
+        res.on('data', (chunk: Buffer) => {
+          responseBody += chunk.toString();
+        });
+        res.on('end', () => {
+          resolve({
+            statusCode: res.statusCode ?? 0,
+            headers: res.headers as Record<string, string>,
+            body: responseBody,
+          });
+        });
+      }
+    );
+    req.on('error', reject);
+    if (body) {
+      req.write(body);
+    }
+    req.end();
+  });
+}
+
+describe('webhook routing integration', () => {
+  let server: Server;
+  let registry: WebhookRegistry;
+  let store: NodeStore;
+
+  beforeAll(() => {
+    server = createServer((req, res) => {
+      // Add CORS headers
+      res.setHeader('Access-Control-Allow-Origin', '*');
+      res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+      res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+
+      // Handle preflight
+      if (req.method === 'OPTIONS') {
+        res.writeHead(204);
+        res.end();
+        return;
+      }
+
+      if (req.url && isWebhookRequest(req.url)) {
+        void webhookHandler(req, res);
+        return;
+      }
+
+      res.writeHead(404);
+      res.end('Not found');
+    });
+
+    return new Promise<void>((resolve) => {
+      server.listen(0, () => resolve());
+    });
+  });
+
+  afterAll(() => {
+    return new Promise<void>((resolve) => {
+      server.close(() => resolve());
+    });
+  });
+
+  beforeEach(() => {
+    registry = new WebhookRegistry();
+    setDefaultWebhookRegistry(registry);
+    store = new NodeStore();
+    setDefaultStore(store);
+  });
+
+  describe('webhook endpoint routing', () => {
+    it('should return 404 for unregistered webhook', async () => {
+      const response = await makeRequest(server, '/_webhooks/unknown/path', {
+        body: '{}',
+      });
+
+      expect(response.statusCode).toBe(404);
+      const body = JSON.parse(response.body);
+      expect(body.error).toBe('Webhook handler not found');
+    });
+
+    it('should route to correct handler based on plugin and path', async () => {
+      let handlerCalled = false;
+      let receivedBody: unknown;
+
+      const webhook: WebhookRegistration = {
+        path: 'entry-update',
+        handler: async (_req, res, context) => {
+          handlerCalled = true;
+          receivedBody = context.body;
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ received: true }));
+        },
+      };
+
+      registry.register('contentful', webhook);
+
+      const payload = { type: 'entry.publish', entryId: '123' };
+      const response = await makeRequest(
+        server,
+        '/_webhooks/contentful/entry-update',
+        {
+          body: JSON.stringify(payload),
+        }
+      );
+
+      expect(response.statusCode).toBe(200);
+      expect(handlerCalled).toBe(true);
+      expect(receivedBody).toEqual(payload);
+    });
+
+    it('should include CORS headers in webhook responses', async () => {
+      registry.register('plugin', {
+        path: 'test',
+        handler: async (_req, res) => {
+          res.writeHead(200);
+          res.end('OK');
+        },
+      });
+
+      const response = await makeRequest(server, '/_webhooks/plugin/test', {
+        body: '{}',
+      });
+
+      expect(response.headers['access-control-allow-origin']).toBe('*');
+    });
+
+    it('should return 405 for GET requests to webhook endpoints', async () => {
+      registry.register('plugin', {
+        path: 'test',
+        handler: async (_req, res) => {
+          res.writeHead(200);
+          res.end('OK');
+        },
+      });
+
+      const response = await makeRequest(server, '/_webhooks/plugin/test', {
+        method: 'GET',
+      });
+
+      expect(response.statusCode).toBe(405);
+    });
+  });
+
+  describe('webhook handler receives correct context', () => {
+    it('should provide store and actions in context', async () => {
+      let receivedContext: WebhookHandlerContext | undefined;
+
+      registry.register('test-plugin', {
+        path: 'sync',
+        handler: async (_req, res, context) => {
+          receivedContext = context;
+          res.writeHead(200);
+          res.end('OK');
+        },
+      });
+
+      await makeRequest(server, '/_webhooks/test-plugin/sync', {
+        body: '{}',
+      });
+
+      expect(receivedContext).toBeDefined();
+      expect(receivedContext?.store).toBe(store);
+      expect(receivedContext?.actions).toBeDefined();
+      expect(typeof receivedContext?.actions.createNode).toBe('function');
+      expect(typeof receivedContext?.actions.deleteNode).toBe('function');
+      expect(typeof receivedContext?.actions.getNode).toBe('function');
+    });
+
+    it('should provide rawBody buffer in context', async () => {
+      let receivedRawBody: Buffer | undefined;
+
+      registry.register('plugin', {
+        path: 'test',
+        handler: async (_req, res, context) => {
+          receivedRawBody = context.rawBody;
+          res.writeHead(200);
+          res.end('OK');
+        },
+      });
+
+      const payload = { test: 'data' };
+      await makeRequest(server, '/_webhooks/plugin/test', {
+        body: JSON.stringify(payload),
+      });
+
+      expect(receivedRawBody).toBeInstanceOf(Buffer);
+      expect(receivedRawBody?.toString()).toBe(JSON.stringify(payload));
+    });
+  });
+
+  describe('node creation from webhook', () => {
+    it('should allow creating nodes via webhook handler', async () => {
+      registry.register('cms-plugin', {
+        path: 'content-update',
+        handler: async (_req, res, context) => {
+          const { body, actions } = context;
+          const payload = body as { contentId: string; title: string };
+
+          await actions.createNode({
+            internal: {
+              id: payload.contentId,
+              type: 'ContentEntry',
+              owner: 'cms-plugin',
+            },
+            title: payload.title,
+          });
+
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ created: true }));
+        },
+      });
+
+      const payload = { contentId: 'entry-123', title: 'Test Entry' };
+      const response = await makeRequest(
+        server,
+        '/_webhooks/cms-plugin/content-update',
+        {
+          body: JSON.stringify(payload),
+        }
+      );
+
+      expect(response.statusCode).toBe(200);
+
+      // Verify node was created in store
+      const nodes = store.getAll();
+      expect(nodes.length).toBe(1);
+
+      const node = nodes[0];
+      expect(node).toBeDefined();
+      expect(node!.internal.id).toBe('entry-123');
+      expect(node!.internal.type).toBe('ContentEntry');
+      expect((node as unknown as { title: string }).title).toBe('Test Entry');
+    });
+
+    it('should allow deleting nodes via webhook handler', async () => {
+      // First create a node
+      store.set({
+        internal: {
+          id: 'node-to-delete',
+          type: 'TestNode',
+          contentDigest: 'abc123',
+          owner: 'test',
+          createdAt: Date.now(),
+          modifiedAt: Date.now(),
+        },
+      });
+
+      registry.register('plugin', {
+        path: 'delete',
+        handler: async (_req, res, context) => {
+          const { body, actions } = context;
+          const payload = body as { nodeId: string };
+
+          await actions.deleteNode(payload.nodeId);
+
+          res.writeHead(200);
+          res.end('OK');
+        },
+      });
+
+      await makeRequest(server, '/_webhooks/plugin/delete', {
+        body: JSON.stringify({ nodeId: 'node-to-delete' }),
+      });
+
+      // Verify node was deleted
+      expect(store.get('node-to-delete')).toBeUndefined();
+    });
+  });
+
+  describe('signature verification', () => {
+    it('should return 401 when signature verification fails', async () => {
+      registry.register('secure-plugin', {
+        path: 'secure-hook',
+        handler: async (_req, res) => {
+          res.writeHead(200);
+          res.end('OK');
+        },
+        verifySignature: (_req, _body) => {
+          return false; // Always fail
+        },
+      });
+
+      const response = await makeRequest(
+        server,
+        '/_webhooks/secure-plugin/secure-hook',
+        {
+          body: '{}',
+        }
+      );
+
+      expect(response.statusCode).toBe(401);
+      const body = JSON.parse(response.body);
+      expect(body.error).toBe('Invalid signature');
+    });
+
+    it('should call handler when signature is valid', async () => {
+      let handlerCalled = false;
+
+      registry.register('secure-plugin', {
+        path: 'secure-hook',
+        handler: async (_req, res) => {
+          handlerCalled = true;
+          res.writeHead(200);
+          res.end('OK');
+        },
+        verifySignature: (req, _body) => {
+          // Check for expected header
+          return req.headers['x-webhook-signature'] === 'valid-signature';
+        },
+      });
+
+      const response = await makeRequest(
+        server,
+        '/_webhooks/secure-plugin/secure-hook',
+        {
+          body: '{}',
+          headers: {
+            'x-webhook-signature': 'valid-signature',
+          },
+        }
+      );
+
+      expect(response.statusCode).toBe(200);
+      expect(handlerCalled).toBe(true);
+    });
+  });
+
+  describe('error handling', () => {
+    it('should return 400 for invalid JSON body', async () => {
+      registry.register('plugin', {
+        path: 'test',
+        handler: async (_req, res) => {
+          res.writeHead(200);
+          res.end('OK');
+        },
+      });
+
+      const response = await makeRequest(server, '/_webhooks/plugin/test', {
+        body: 'not valid json {{{',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+      });
+
+      expect(response.statusCode).toBe(400);
+      const body = JSON.parse(response.body);
+      expect(body.error).toBe('Invalid JSON body');
+    });
+
+    it('should return 500 when handler throws', async () => {
+      registry.register('plugin', {
+        path: 'error',
+        handler: async () => {
+          throw new Error('Something went wrong');
+        },
+      });
+
+      const response = await makeRequest(server, '/_webhooks/plugin/error', {
+        body: '{}',
+      });
+
+      expect(response.statusCode).toBe(500);
+      const body = JSON.parse(response.body);
+      expect(body.error).toBe('Internal server error');
+    });
+  });
+
+  describe('multiple plugins', () => {
+    it('should route webhooks to correct plugin handlers', async () => {
+      const calls: string[] = [];
+
+      registry.register('plugin-a', {
+        path: 'update',
+        handler: async (_req, res) => {
+          calls.push('plugin-a');
+          res.writeHead(200);
+          res.end('A');
+        },
+      });
+
+      registry.register('plugin-b', {
+        path: 'update',
+        handler: async (_req, res) => {
+          calls.push('plugin-b');
+          res.writeHead(200);
+          res.end('B');
+        },
+      });
+
+      // Call plugin-a
+      await makeRequest(server, '/_webhooks/plugin-a/update', { body: '{}' });
+      expect(calls).toEqual(['plugin-a']);
+
+      // Call plugin-b
+      await makeRequest(server, '/_webhooks/plugin-b/update', { body: '{}' });
+      expect(calls).toEqual(['plugin-a', 'plugin-b']);
+    });
+  });
+});
diff --git a/packages/core/tests/unit/handlers/webhook.test.ts b/packages/core/tests/unit/handlers/webhook.test.ts
new file mode 100644
index 0000000..173030f
--- /dev/null
+++ b/packages/core/tests/unit/handlers/webhook.test.ts
@@ -0,0 +1,681 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { EventEmitter } from 'node:events';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import {
+  isWebhookRequest,
+  parseWebhookUrl,
+  webhookHandler,
+  WEBHOOK_PATH_PREFIX,
+} from '@/handlers/webhook.js';
+import {
+  WebhookRegistry,
+  setDefaultWebhookRegistry,
+  type WebhookRegistration,
+  type WebhookHandlerContext,
+} from '@/webhooks/index.js';
+
+// Create a mock request that extends EventEmitter to support .on() calls
+function createMockRequest(
+  method: string,
+  url: string,
+  headers: Record<string, string> = {}
+): IncomingMessage & EventEmitter {
+  const emitter = new EventEmitter();
+  return Object.assign(emitter, {
+    method,
+    url,
+    headers,
+  }) as IncomingMessage & EventEmitter;
+}
+
+// Create a mock response
+function createMockResponse(): ServerResponse & {
+  _statusCode: number;
+  _headers: Record<string, string>;
+  _body: string;
+  headersSent: boolean;
+} {
+  const res = {
+    _statusCode: 0,
+    _headers: {} as Record<string, string>,
+    _body: '',
+    headersSent: false,
+    writeHead(statusCode: number, headers?: Record<string, string>) {
+      this._statusCode = statusCode;
+      this.headersSent = true;
+      if (headers) {
+        Object.assign(this._headers, headers);
+      }
+      return this;
+    },
+    end(body?: string) {
+      if (body) {
+        this._body = body;
+      }
+    },
+  };
+  return res as unknown as ServerResponse & {
+    _statusCode: number;
+    _headers: Record<string, string>;
+    _body: string;
+    headersSent: boolean;
+  };
+}
+
+// Helper to emit body data on a mock request after a small delay
+// This allows the handler to set up event listeners before data is emitted
+function emitBody(
+  req: IncomingMessage & EventEmitter,
+  body: string | Buffer
+): void {
+  const buffer = Buffer.isBuffer(body) ? body : Buffer.from(body);
+  // Use setImmediate to allow the handler to register event listeners first
+  setImmediate(() => {
+    req.emit('data', buffer);
+    req.emit('end');
+  });
+}
+
+// Sample webhook handler for testing
+function createTestWebhook(
+  path: string,
+  options: {
+    handler?: WebhookRegistration['handler'];
+    verifySignature?: WebhookRegistration['verifySignature'];
+  } = {}
+): WebhookRegistration {
+  const webhook: WebhookRegistration = {
+    path,
+    handler:
+      options.handler ||
+      (async (_req, res, _context) => {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ received: true }));
+      }),
+  };
+  if (options.verifySignature) {
+    webhook.verifySignature = options.verifySignature;
+  }
+  return webhook;
+}
+
+describe('isWebhookRequest', () => {
+  it('should return true for valid webhook URLs', () => {
+    expect(isWebhookRequest('/_webhooks/plugin/path')).toBe(true);
+    expect(isWebhookRequest('/_webhooks/contentful/entry-update')).toBe(true);
+    expect(isWebhookRequest('/_webhooks/my-plugin/sync')).toBe(true);
+  });
+
+  it('should return false for non-webhook URLs', () => {
+    expect(isWebhookRequest('/graphql')).toBe(false);
+    expect(isWebhookRequest('/health')).toBe(false);
+    expect(isWebhookRequest('/ready')).toBe(false);
+    expect(isWebhookRequest('/webhooks/plugin/path')).toBe(false);
+    expect(isWebhookRequest('/_webhook/plugin/path')).toBe(false);
+    expect(isWebhookRequest('/')).toBe(false);
+  });
+
+  it('should handle edge cases', () => {
+    expect(isWebhookRequest('')).toBe(false);
+    expect(isWebhookRequest('/_webhooks/')).toBe(true);
+    expect(isWebhookRequest('/_webhooks')).toBe(false);
+  });
+});
+
+describe('parseWebhookUrl', () => {
+  it('should parse valid webhook URLs', () => {
+    expect(parseWebhookUrl('/_webhooks/plugin/path')).toEqual({
+      pluginName: 'plugin',
+      webhookPath: 'path',
+    });
+
+    expect(parseWebhookUrl('/_webhooks/contentful/entry-update')).toEqual({
+      pluginName: 'contentful',
+      webhookPath: 'entry-update',
+    });
+
+    expect(parseWebhookUrl('/_webhooks/my-plugin/sync')).toEqual({
+      pluginName: 'my-plugin',
+      webhookPath: 'sync',
+    });
+  });
+
+  it('should handle multi-segment paths', () => {
+    expect(parseWebhookUrl('/_webhooks/plugin/path/subpath')).toEqual({
+      pluginName: 'plugin',
+      webhookPath: 'path/subpath',
+    });
+  });
+
+  it('should handle query strings', () => {
+    expect(parseWebhookUrl('/_webhooks/plugin/path?foo=bar')).toEqual({
+      pluginName: 'plugin',
+      webhookPath: 'path',
+    });
+  });
+
+  it('should return null for invalid URLs', () => {
+    expect(parseWebhookUrl('/graphql')).toBeNull();
+    expect(parseWebhookUrl('/_webhooks/')).toBeNull();
+    expect(parseWebhookUrl('/_webhooks/plugin')).toBeNull();
+    expect(parseWebhookUrl('/_webhooks/plugin/')).toBeNull();
+  });
+});
+
+describe('WEBHOOK_PATH_PREFIX', () => {
+  it('should be /_webhooks/', () => {
+    expect(WEBHOOK_PATH_PREFIX).toBe('/_webhooks/');
+  });
+});
+
+describe('webhookHandler', () => {
+  let registry: WebhookRegistry;
+
+  beforeEach(() => {
+    registry = new WebhookRegistry();
+    setDefaultWebhookRegistry(registry);
+  });
+
+  describe('HTTP method validation', () => {
+    it('should return 405 for GET requests', async () => {
+      const req = createMockRequest('GET', '/_webhooks/plugin/path');
+      const res = createMockResponse();
+
+      await webhookHandler(req, res);
+
+      expect(res._statusCode).toBe(405);
+      const body = JSON.parse(res._body);
+      expect(body.error).toBe('Method not allowed');
+    });
+
+    it('should return 405 for PUT requests', async () => {
+      const req = createMockRequest('PUT', '/_webhooks/plugin/path');
+      const res = createMockResponse();
+
+      await webhookHandler(req, res);
+
+      expect(res._statusCode).toBe(405);
+    });
+
+    it('should return 405 for DELETE requests', async () => {
+      const req = createMockRequest('DELETE', '/_webhooks/plugin/path');
+      const res = createMockResponse();
+
+      await webhookHandler(req, res);
+
+      expect(res._statusCode).toBe(405);
+    });
+  });
+
+  describe('URL parsing and handler lookup', () => {
+    it('should return 404 for invalid URL format', async () => {
+      const req = createMockRequest('POST', '/_webhooks/');
+      const res = createMockResponse();
+
+      emitBody(req, '{}');
+      await webhookHandler(req, res);
+
+      expect(res._statusCode).toBe(404);
+      const body = JSON.parse(res._body);
+      expect(body.error).toBe('Invalid webhook URL format');
+    });
+
+    it('should return 404 when no handler is registered', async () => {
+      const req = createMockRequest('POST', '/_webhooks/unknown-plugin/path');
+      const res = createMockResponse();
+
+      emitBody(req, '{}');
+      await webhookHandler(req, res);
+
+      expect(res._statusCode).toBe(404);
+      const body = JSON.parse(res._body);
+      expect(body.error).toBe('Webhook handler not found');
+    });
+
+    it('should return 404 for wrong plugin name', async () => {
+      registry.register('plugin-a', createTestWebhook('path'));
+
+      const req = createMockRequest('POST', '/_webhooks/plugin-b/path');
+      const res = createMockResponse();
+
+      emitBody(req, '{}');
+      await webhookHandler(req, res);
+
+      expect(res._statusCode).toBe(404);
+    });
+
+    it('should return 404 for wrong path', async () => {
+      registry.register('plugin', createTestWebhook('path-a'));
+
+      const req = createMockRequest('POST', '/_webhooks/plugin/path-b');
+      const res = createMockResponse();
+
+      emitBody(req, '{}');
+      await webhookHandler(req, res);
+
+      expect(res._statusCode).toBe(404);
+    });
+  });
+
+  describe('signature verification', () => {
+    it('should return 401 when verifySignature returns false', async () => {
+      const consoleWarnSpy = vi
+        .spyOn(console, 'warn')
+        .mockImplementation(() => {});
+
+      registry.register(
+        'plugin',
+        createTestWebhook('path', {
+          verifySignature: () => false,
+        })
+      );
+
+      const req = createMockRequest('POST', '/_webhooks/plugin/path');
+      const res = createMockResponse();
+
+      emitBody(req, '{}');
+      await webhookHandler(req, res);
+
+      expect(res._statusCode).toBe(401);
+      const body = JSON.parse(res._body);
+      expect(body.error).toBe('Invalid signature');
+      expect(consoleWarnSpy).toHaveBeenCalled();
+
+      consoleWarnSpy.mockRestore();
+    });
+
+    it('should return 401 when verifySignature throws', async () => {
+      const consoleErrorSpy = vi
+        .spyOn(console, 'error')
+        .mockImplementation(() => {});
+
+      registry.register(
+        'plugin',
+        createTestWebhook('path', {
+          verifySignature: () => {
+            throw new Error('Signature error');
+          },
+        })
+      );
+
+      const req = createMockRequest('POST', '/_webhooks/plugin/path');
+      const res = createMockResponse();
+
+      emitBody(req, '{}');
+      await webhookHandler(req, res);
+
+      expect(res._statusCode).toBe(401);
+      const body = JSON.parse(res._body);
+      expect(body.error).toBe('Signature verification failed');
+
+      consoleErrorSpy.mockRestore();
+    });
+
+    it('should call handler when verifySignature returns true', async () => {
+      const consoleLogSpy = vi
+        .spyOn(console, 'log')
+        .mockImplementation(() => {});
+      const handlerCalled = vi.fn();
+
+      registry.register(
+        'plugin',
+        createTestWebhook('path', {
+          verifySignature: () => true,
+          handler: async (_req, res, _context) => {
+            handlerCalled();
+            res.writeHead(200);
+            res.end('OK');
+          },
+        })
+      );
+
+      const req = createMockRequest('POST', '/_webhooks/plugin/path');
+      const res = createMockResponse();
+
+      emitBody(req, '{}');
+      await webhookHandler(req, res);
+
+      expect(res._statusCode).toBe(200);
+      expect(handlerCalled).toHaveBeenCalled();
+
+      consoleLogSpy.mockRestore();
+    });
+
+    it('should support async verifySignature', async () => {
+      const consoleLogSpy = vi
+        .spyOn(console, 'log')
+        .mockImplementation(() => {});
+
+      registry.register(
+        'plugin',
+        createTestWebhook('path', {
+          verifySignature: async () => {
+            await new Promise((resolve) => setTimeout(resolve, 10));
+            return true;
+          },
+        })
+      );
+
+      const req = createMockRequest('POST', '/_webhooks/plugin/path');
+      const res = createMockResponse();
+
+      emitBody(req, '{}');
+      await webhookHandler(req, res);
+
+      expect(res._statusCode).toBe(200);
+
+      consoleLogSpy.mockRestore();
+    });
+
+    it('should skip verification if no verifySignature defined', async () => {
+      const consoleLogSpy = vi
+        .spyOn(console, 'log')
+        .mockImplementation(() => {});
+
+      registry.register('plugin', createTestWebhook('path'));
+
+      const req = createMockRequest('POST', '/_webhooks/plugin/path');
+      const res = createMockResponse();
+
+      emitBody(req, '{}');
+      await webhookHandler(req, res);
+
+      expect(res._statusCode).toBe(200);
+
+      consoleLogSpy.mockRestore();
+    });
+  });
+
+  describe('JSON body parsing', () => {
+    it('should return 400 for invalid JSON with application/json content-type', async () => {
+      registry.register('plugin', createTestWebhook('path'));
+
+      const req = createMockRequest('POST', '/_webhooks/plugin/path', {
+        'content-type': 'application/json',
+      });
+      const res = createMockResponse();
+
+      emitBody(req, 'invalid json {{{');
+      await webhookHandler(req, res);
+
+      expect(res._statusCode).toBe(400);
+      const body = JSON.parse(res._body);
+      expect(body.error).toBe('Invalid JSON body');
+    });
+
+    it('should parse valid JSON body', async () => {
+      const consoleLogSpy = vi
+        .spyOn(console, 'log')
+        .mockImplementation(() => {});
+      let receivedContext: WebhookHandlerContext | undefined;
+
+      registry.register(
+        'plugin',
+        createTestWebhook('path', {
+          handler: async (_req, res, context) => {
+            receivedContext = context;
+            res.writeHead(200);
+            res.end('OK');
+          },
+        })
+      );
+
+      const req = createMockRequest('POST', '/_webhooks/plugin/path', {
+        'content-type': 'application/json',
+      });
+      const res = createMockResponse();
+
+      const payload = { type: 'entry.publish', data: { id: '123' } };
+      emitBody(req, JSON.stringify(payload));
+      await webhookHandler(req, res);
+
+      expect(res._statusCode).toBe(200);
+      expect(receivedContext?.body).toEqual(payload);
+
+      consoleLogSpy.mockRestore();
+    });
+
+    it('should pass undefined body for non-JSON content types', async () => {
+      const consoleLogSpy = vi
+        .spyOn(console, 'log')
+        .mockImplementation(() => {});
+      let receivedContext: WebhookHandlerContext | undefined;
+
+      registry.register(
+        'plugin',
+        createTestWebhook('path', {
+          handler: async (_req, res, context) => {
+            receivedContext = context;
+            res.writeHead(200);
+            res.end('OK');
+          },
+        })
+      );
+
+      const req = createMockRequest('POST', '/_webhooks/plugin/path', {
+        'content-type': 'text/plain',
+      });
+      const res = createMockResponse();
+
+      emitBody(req, 'plain text body');
+      await webhookHandler(req, res);
+
+      expect(res._statusCode).toBe(200);
+      expect(receivedContext?.body).toBeUndefined();
+
+      consoleLogSpy.mockRestore();
+    });
+
+    it('should always pass rawBody buffer', async () => {
+      const consoleLogSpy = vi
+        .spyOn(console, 'log')
+        .mockImplementation(() => {});
+      let receivedContext: WebhookHandlerContext | undefined;
+
+      registry.register(
+        'plugin',
+        createTestWebhook('path', {
+          handler: async (_req, res, context) => {
+            receivedContext = context;
+            res.writeHead(200);
+            res.end('OK');
+          },
+        })
+      );
+
+      const req = createMockRequest('POST', '/_webhooks/plugin/path');
+      const res = createMockResponse();
+
+      const bodyText = 'raw body content';
+      emitBody(req, bodyText);
+      await webhookHandler(req, res);
+
+      expect(res._statusCode).toBe(200);
+      expect(receivedContext?.rawBody).toBeInstanceOf(Buffer);
+      expect(receivedContext?.rawBody.toString()).toBe(bodyText);
+
+      consoleLogSpy.mockRestore();
+    });
+  });
+
+  describe('handler execution', () => {
+    it('should call handler with correct context', async () => {
+      const consoleLogSpy = vi
+        .spyOn(console, 'log')
+        .mockImplementation(() => {});
+      let receivedContext: WebhookHandlerContext | undefined;
+
+      registry.register(
+        'test-plugin',
+        createTestWebhook('update', {
+          handler: async (_req, res, context) => {
+            receivedContext = context;
+            res.writeHead(200);
+            res.end('OK');
+          },
+        })
+      );
+
+      const req = createMockRequest('POST', '/_webhooks/test-plugin/update', {
+        'content-type': 'application/json',
+      });
+      const res = createMockResponse();
+
+      emitBody(req, '{"test": true}');
+      await webhookHandler(req, res);
+
+      expect(receivedContext).toBeDefined();
+      expect(receivedContext?.store).toBeDefined();
+      expect(receivedContext?.actions).toBeDefined();
+      expect(receivedContext?.actions.createNode).toBeDefined();
+      expect(receivedContext?.actions.deleteNode).toBeDefined();
+      expect(receivedContext?.rawBody).toBeInstanceOf(Buffer);
+      expect(receivedContext?.body).toEqual({ test: true });
+
+      consoleLogSpy.mockRestore();
+    });
+
+    it('should return 500 when handler throws', async () => {
+      const consoleLogSpy = vi
+        .spyOn(console, 'log')
+        .mockImplementation(() => {});
+      const consoleErrorSpy = vi
+        .spyOn(console, 'error')
+        .mockImplementation(() => {});
+
+      registry.register(
+        'plugin',
+        createTestWebhook('path', {
+          handler: async () => {
+            throw new Error('Handler error');
+          },
+        })
+      );
+
+      const req = createMockRequest('POST', '/_webhooks/plugin/path');
+      const res = createMockResponse();
+
+      emitBody(req, '{}');
+      await webhookHandler(req, res);
+
+      expect(res._statusCode).toBe(500);
+      const body = JSON.parse(res._body);
+      expect(body.error).toBe('Internal server error');
+      expect(consoleErrorSpy).toHaveBeenCalled();
+
+      consoleLogSpy.mockRestore();
+      consoleErrorSpy.mockRestore();
+    });
+
+    it('should not send error response if headers already sent', async () => {
+      const consoleLogSpy = vi
+        .spyOn(console, 'log')
+        .mockImplementation(() => {});
+      const consoleErrorSpy = vi
+        .spyOn(console, 'error')
+        .mockImplementation(() => {});
+
+      registry.register(
+        'plugin',
+        createTestWebhook('path', {
+          handler: async (_req, res) => {
+            res.writeHead(202);
+            res.end('Accepted');
+            throw new Error('Post-response error');
+          },
+        })
+      );
+
+      const req = createMockRequest('POST', '/_webhooks/plugin/path');
+      const res = createMockResponse();
+
+      emitBody(req, '{}');
+      await webhookHandler(req, res);
+
+      // Should keep the 202 status, not override with 500
+      expect(res._statusCode).toBe(202);
+      expect(res._body).toBe('Accepted');
+
+      consoleLogSpy.mockRestore();
+      consoleErrorSpy.mockRestore();
+    });
+
+    it('should allow handler to set custom response', async () => {
+      const consoleLogSpy = vi
+        .spyOn(console, 'log')
+        .mockImplementation(() => {});
+
+      registry.register(
+        'plugin',
+        createTestWebhook('path', {
+          handler: async (_req, res) => {
+            res.writeHead(201, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ status: 'created' }));
+          },
+        })
+      );
+
+      const req = createMockRequest('POST', '/_webhooks/plugin/path');
+      const res = createMockResponse();
+
+      emitBody(req, '{}');
+      await webhookHandler(req, res);
+
+      expect(res._statusCode).toBe(201);
+      const body = JSON.parse(res._body);
+      expect(body.status).toBe('created');
+
+      consoleLogSpy.mockRestore();
+    });
+
+    it('should log webhook received message', async () => {
+      const consoleLogSpy = vi
+        .spyOn(console, 'log')
+        .mockImplementation(() => {});
+
+      registry.register('my-plugin', createTestWebhook('my-path'));
+
+      const req = createMockRequest('POST', '/_webhooks/my-plugin/my-path');
+      const res = createMockResponse();
+
+      emitBody(req, '{}');
+      await webhookHandler(req, res);
+
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        'Webhook received: my-plugin/my-path'
+      );
+
+      consoleLogSpy.mockRestore();
+    });
+  });
+
+  describe('body size limit', () => {
+    it('should return 413 for oversized body', async () => {
+      registry.register('plugin', createTestWebhook('path'));
+
+      const req = createMockRequest('POST', '/_webhooks/plugin/path');
+      const res = createMockResponse();
+
+      // Add destroy method to mock request
+      let destroyed = false;
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      (req as any).destroy = () => {
+        destroyed = true;
+      };
+
+      // Create a body larger than 1MB and emit immediately
+      const largeBody = Buffer.alloc(1024 * 1024 + 1, 'x');
+      setImmediate(() => {
+        req.emit('data', largeBody);
+        // Don't emit 'end' - the handler should reject before that
+      });
+
+      await webhookHandler(req, res);
+
+      expect(res._statusCode).toBe(413);
+      const body = JSON.parse(res._body);
+      expect(body.error).toBe('Payload too large');
+      expect(destroyed).toBe(true);
+    });
+  });
+});

From 9113f7f90d3b980e6e88ea3557189a6ea82d4227 Mon Sep 17 00:00:00 2001
From: dawidurbanski <hi@dawidurbanski.com>
Date: Sun, 21 Dec 2025 21:03:38 +0100
Subject: [PATCH 06/46] feat(core): add webhook queue with debouncing and
 lifecycle hooks

Implement webhook queue system that batches incoming webhooks and
processes them after a configurable debounce period. This prevents
N rapid webhook events from triggering N separate processing cycles.

Features:
- WebhookQueue class with configurable debounceMs (default 5s)
- Maximum queue size before forced processing (default 100)
- Lifecycle hooks for custom processing:
  - onWebhookReceived: transform/filter webhooks before queuing
  - onBeforeWebhookTriggered: run before batch (e.g., cache invalidation)
  - onAfterWebhookTriggered: run after batch (e.g., trigger rebuild)
- Graceful shutdown flushes pending webhooks
- Config via remote.webhooks.debounceMs, hooks, maxQueueSize

Breaking changes:
- Webhook HTTP response changed from 200 to 202 Accepted
- Webhooks processed asynchronously after debounce period

Closes #62
---
 .changeset/webhook-queue-debouncing.md        |  49 +++
 packages/core/src/handlers/webhook.ts         |  64 ++-
 packages/core/src/loader.ts                   |  39 ++
 packages/core/src/start-server.ts             |  63 ++-
 packages/core/src/webhooks/hooks.ts           | 172 ++++++++
 packages/core/src/webhooks/index.ts           |  37 ++
 packages/core/src/webhooks/processor.ts       | 220 ++++++++++
 packages/core/src/webhooks/queue.ts           | 297 +++++++++++++
 .../tests/integration/webhook-routing.test.ts |  59 ++-
 .../core/tests/unit/handlers/webhook.test.ts  | 343 +++++++++------
 .../core/tests/unit/webhooks/queue.test.ts    | 409 ++++++++++++++++++
 11 files changed, 1585 insertions(+), 167 deletions(-)
 create mode 100644 .changeset/webhook-queue-debouncing.md
 create mode 100644 packages/core/src/webhooks/hooks.ts
 create mode 100644 packages/core/src/webhooks/processor.ts
 create mode 100644 packages/core/src/webhooks/queue.ts
 create mode 100644 packages/core/tests/unit/webhooks/queue.test.ts

diff --git a/.changeset/webhook-queue-debouncing.md b/.changeset/webhook-queue-debouncing.md
new file mode 100644
index 0000000..aa3cf87
--- /dev/null
+++ b/.changeset/webhook-queue-debouncing.md
@@ -0,0 +1,49 @@
+---
+'universal-data-layer': minor
+---
+
+Add webhook queue with debouncing and lifecycle hooks
+
+This release introduces a webhook queue system that batches incoming webhooks and processes them after a configurable debounce period. This prevents N rapid webhook events (e.g., 30 Contentful entry publishes) from triggering N separate processing cycles.
+
+**Features:**
+
+- Webhook queue with configurable debounce period (`remote.webhooks.debounceMs`, default 5000ms)
+- Maximum queue size before forced processing (`remote.webhooks.maxQueueSize`, default 100)
+- Lifecycle hooks for custom processing:
+  - `onWebhookReceived`: Transform or filter webhooks before queuing
+  - `onBeforeWebhookTriggered`: Run before batch processing (e.g., invalidate CDN cache)
+  - `onAfterWebhookTriggered`: Run after batch processing (e.g., trigger rebuild)
+- Graceful shutdown flushes pending webhooks
+- HTTP response changed from 200 to 202 Accepted (webhook is queued)
+
+**Example configuration:**
+
+```typescript
+export const { config } = defineConfig({
+  remote: {
+    webhooks: {
+      debounceMs: 5000,
+      maxQueueSize: 100,
+      hooks: {
+        onWebhookReceived: async ({ webhook }) => {
+          // Skip drafts
+          if (!webhook.body?.sys?.publishedAt) return null;
+          return webhook;
+        },
+        onBeforeWebhookTriggered: async ({ batch }) => {
+          await invalidateCDNCache();
+        },
+        onAfterWebhookTriggered: async ({ batch }) => {
+          await triggerRebuild();
+        },
+      },
+    },
+  },
+});
+```
+
+**Breaking Changes:**
+
+- Webhook HTTP responses now return 202 Accepted instead of 200 OK
+- Webhooks are processed asynchronously after debounce period instead of immediately
diff --git a/packages/core/src/handlers/webhook.ts b/packages/core/src/handlers/webhook.ts
index 4aea563..557186b 100644
--- a/packages/core/src/handlers/webhook.ts
+++ b/packages/core/src/handlers/webhook.ts
@@ -3,13 +3,19 @@
  *
  * Routes incoming webhook requests to the appropriate plugin handler.
  * URL format: POST /_webhooks/{pluginName}/{path}
+ *
+ * Webhooks are queued and processed in batches after a debounce period.
+ * This prevents N rapid webhooks from triggering N separate processing cycles.
  */
 
 import type { IncomingMessage, ServerResponse } from 'node:http';
-import { defaultWebhookRegistry } from '@/webhooks/index.js';
+import {
+  defaultWebhookRegistry,
+  defaultWebhookQueue,
+  getWebhookHooks,
+  type QueuedWebhook,
+} from '@/webhooks/index.js';
 import { defaultStore } from '@/nodes/defaultStore.js';
-import { createNodeActions } from '@/nodes/actions/index.js';
-import type { WebhookHandlerContext } from '@/webhooks/index.js';
 
 /** URL path prefix for webhook endpoints */
 export const WEBHOOK_PATH_PREFIX = '/_webhooks/';
@@ -177,26 +183,48 @@ export async function webhookHandler(
     }
   }
 
-  // Create context for the handler
-  const actions = createNodeActions(defaultStore, pluginName);
-  const context: WebhookHandlerContext = {
-    store: defaultStore,
-    actions,
+  console.log(`Webhook received: ${pluginName}/${webhookPath}`);
+
+  // Create the queued webhook object
+  let queuedWebhook: QueuedWebhook = {
+    pluginName,
+    path: webhookPath,
     rawBody,
     body,
+    headers: req.headers as Record<string, string | string[] | undefined>,
+    timestamp: Date.now(),
   };
 
-  console.log(`Webhook received: ${pluginName}/${webhookPath}`);
+  // Run onWebhookReceived hook if configured
+  const hooks = getWebhookHooks();
+  if (hooks.onWebhookReceived) {
+    try {
+      console.log('🪝 Running onWebhookReceived hook...');
+      const result = await hooks.onWebhookReceived({
+        webhook: queuedWebhook,
+        store: defaultStore,
+      });
+
+      if (result === null) {
+        // Hook returned null, skip this webhook
+        console.log('⏭️ Webhook skipped by onWebhookReceived hook');
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ skipped: true }));
+        return;
+      }
 
-  // Call the handler
-  try {
-    await handler.handler(req, res, context);
-  } catch (error) {
-    console.error(`Webhook handler error: ${pluginName}/${webhookPath}`, error);
-    // Only send error response if headers haven't been sent
-    if (!res.headersSent) {
-      res.writeHead(500, { 'Content-Type': 'application/json' });
-      res.end(JSON.stringify({ error: 'Internal server error' }));
+      // Use the transformed webhook
+      queuedWebhook = result;
+    } catch (error) {
+      console.error('❌ onWebhookReceived hook error:', error);
+      // Continue with original webhook despite hook error
     }
   }
+
+  // Queue the webhook for batch processing
+  defaultWebhookQueue.enqueue(queuedWebhook);
+
+  // Respond immediately with 202 Accepted
+  res.writeHead(202, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify({ queued: true }));
 }
diff --git a/packages/core/src/loader.ts b/packages/core/src/loader.ts
index c5eb915..0b2db52 100644
--- a/packages/core/src/loader.ts
+++ b/packages/core/src/loader.ts
@@ -17,6 +17,7 @@ import {
   defaultWebhookRegistry,
   type WebhookRegistry,
   type WebhookRegistration,
+  type WebhookHooksConfig,
 } from '@/webhooks/index.js';
 
 export const pluginTypes = ['core', 'source', 'other'] as const;
@@ -83,6 +84,40 @@ export interface CodegenConfig {
   )[];
 }
 
+/**
+ * Configuration for remote webhook handling.
+ */
+export interface RemoteWebhooksConfig {
+  /**
+   * Debounce period in milliseconds.
+   * After each webhook, the queue waits this long for more webhooks before processing.
+   * @default 5000
+   */
+  debounceMs?: number;
+
+  /**
+   * Maximum queue size before forced processing.
+   * When the queue reaches this size, it will process immediately regardless of debounce.
+   * @default 100
+   */
+  maxQueueSize?: number;
+
+  /**
+   * Lifecycle hooks for webhook processing.
+   */
+  hooks?: WebhookHooksConfig;
+}
+
+/**
+ * Configuration for remote data synchronization.
+ */
+export interface RemoteConfig {
+  /**
+   * Webhook queue and processing configuration.
+   */
+  webhooks?: RemoteWebhooksConfig;
+}
+
 /**
  * Core UDL configuration object
  */
@@ -114,6 +149,10 @@ export interface UDLConfig {
    * - Custom `CacheStorage`: Use a custom cache implementation (e.g., Redis, SQLite)
    */
   cache?: CacheStorage | false;
+  /**
+   * Configuration for remote data synchronization (webhooks, etc.).
+   */
+  remote?: RemoteConfig;
 }
 
 /**
diff --git a/packages/core/src/start-server.ts b/packages/core/src/start-server.ts
index afd8f49..dc2b422 100644
--- a/packages/core/src/start-server.ts
+++ b/packages/core/src/start-server.ts
@@ -12,6 +12,13 @@ import { dirname, resolve } from 'node:path';
 import { defaultStore } from '@/nodes/defaultStore.js';
 import { loadManualTestConfigs, type FeatureCodegenInfo } from '@/features.js';
 import { setShuttingDown } from '@/shutdown.js';
+import {
+  defaultWebhookQueue,
+  setDefaultWebhookQueue,
+  WebhookQueue,
+  setWebhookHooks,
+  processWebhookBatch,
+} from '@/webhooks/index.js';
 
 export interface StartServerOptions {
   port?: number;
@@ -54,6 +61,24 @@ export async function startServer(options: StartServerOptions = {}) {
     endpoint,
   });
 
+  // Configure webhook queue with settings from config
+  const webhookConfig = userConfig.remote?.webhooks ?? {};
+  const webhookQueue = new WebhookQueue({
+    debounceMs: webhookConfig.debounceMs ?? 5000,
+    maxQueueSize: webhookConfig.maxQueueSize ?? 100,
+    batchProcessor: processWebhookBatch,
+  });
+  setDefaultWebhookQueue(webhookQueue);
+
+  // Set webhook lifecycle hooks if configured
+  if (webhookConfig.hooks) {
+    setWebhookHooks(webhookConfig.hooks);
+  }
+
+  console.log(
+    `🔗 Webhook queue configured (debounce: ${webhookQueue.getDebounceMs()}ms, maxSize: ${webhookQueue.getMaxQueueSize()})`
+  );
+
   // Collect codegen configs to run after schema is built
   const codegenConfigs: FeatureCodegenInfo[] = [];
 
@@ -349,26 +374,32 @@ export async function startServer(options: StartServerOptions = {}) {
     // Unref the timeout so it doesn't keep the process alive
     forceExitTimeout.unref();
 
-    // Stop accepting new connections and wait for in-flight requests
-    server.close(() => {
-      console.log('✅ HTTP server closed');
+    // Flush webhook queue before closing server
+    console.log('📤 Flushing webhook queue...');
+    void defaultWebhookQueue.flush().then(() => {
+      console.log('📤 Webhook queue flushed');
 
-      // Clear the force exit timeout
-      clearTimeout(forceExitTimeout);
+      // Stop accepting new connections and wait for in-flight requests
+      server.close(() => {
+        console.log('✅ HTTP server closed');
 
-      // Clean up debounce timer if active
-      if (debounceTimer) {
-        clearTimeout(debounceTimer);
-        debounceTimer = null;
-      }
+        // Clear the force exit timeout
+        clearTimeout(forceExitTimeout);
 
-      // Clean up file watcher
-      if (fileWatcher) {
-        fileWatcher.close();
-      }
+        // Clean up debounce timer if active
+        if (debounceTimer) {
+          clearTimeout(debounceTimer);
+          debounceTimer = null;
+        }
 
-      console.log('👋 Shutdown complete');
-      process.exit(0);
+        // Clean up file watcher
+        if (fileWatcher) {
+          fileWatcher.close();
+        }
+
+        console.log('👋 Shutdown complete');
+        process.exit(0);
+      });
     });
   };
 
diff --git a/packages/core/src/webhooks/hooks.ts b/packages/core/src/webhooks/hooks.ts
new file mode 100644
index 0000000..fc90bd4
--- /dev/null
+++ b/packages/core/src/webhooks/hooks.ts
@@ -0,0 +1,172 @@
+/**
+ * Webhook Lifecycle Hooks
+ *
+ * Provides extension points for running custom logic at various stages
+ * of webhook processing. Useful for:
+ * - Transforming incoming webhook payloads
+ * - Invalidating CMS/CDN caches before processing
+ * - Triggering rebuilds after batch processing
+ */
+
+import type { NodeStore } from '@/nodes/store.js';
+import type { QueuedWebhook, WebhookBatch } from './queue.js';
+
+/**
+ * Context passed to the onWebhookReceived hook.
+ */
+export interface WebhookReceivedContext {
+  /** The incoming webhook data */
+  webhook: QueuedWebhook;
+  /** Access to the node store */
+  store: NodeStore;
+}
+
+/**
+ * Context passed to batch lifecycle hooks.
+ */
+export interface WebhookBatchContext {
+  /** The batch of webhooks being processed */
+  batch: WebhookBatch;
+  /** Access to the node store */
+  store: NodeStore;
+}
+
+/**
+ * Called when a webhook is received, before it's added to the queue.
+ * Can transform the webhook data or return null to skip processing.
+ *
+ * @example
+ * ```typescript
+ * onWebhookReceived: async ({ webhook }) => {
+ *   // Skip draft content
+ *   if (!webhook.body?.sys?.publishedAt) {
+ *     return null;
+ *   }
+ *   // Transform the webhook
+ *   return {
+ *     ...webhook,
+ *     body: normalizePayload(webhook.body),
+ *   };
+ * }
+ * ```
+ */
+export type OnWebhookReceivedFn = (
+  context: WebhookReceivedContext
+) => QueuedWebhook | null | Promise<QueuedWebhook | null>;
+
+/**
+ * Called before the debounced batch processing begins.
+ * Useful for cache invalidation, pre-processing, etc.
+ *
+ * @example
+ * ```typescript
+ * onBeforeWebhookTriggered: async ({ batch }) => {
+ *   // Invalidate CDN cache before processing
+ *   await fetch('https://cdn.example.com/purge', {
+ *     method: 'POST',
+ *     body: JSON.stringify({ paths: extractPaths(batch) }),
+ *   });
+ * }
+ * ```
+ */
+export type OnBeforeWebhookTriggeredFn = (
+  context: WebhookBatchContext
+) => void | Promise<void>;
+
+/**
+ * Called after batch processing completes successfully.
+ * Useful for triggering rebuilds, sending notifications, etc.
+ *
+ * @example
+ * ```typescript
+ * onAfterWebhookTriggered: async ({ batch }) => {
+ *   // Trigger a rebuild
+ *   await fetch('https://build.example.com/trigger', {
+ *     method: 'POST',
+ *   });
+ * }
+ * ```
+ */
+export type OnAfterWebhookTriggeredFn = (
+  context: WebhookBatchContext
+) => void | Promise<void>;
+
+/**
+ * Configuration for webhook lifecycle hooks.
+ *
+ * @example
+ * ```typescript
+ * // In udl.config.ts
+ * export const { config } = defineConfig({
+ *   remote: {
+ *     webhooks: {
+ *       debounceMs: 5000,
+ *       hooks: {
+ *         onWebhookReceived: async ({ webhook }) => {
+ *           // Skip drafts
+ *           if (!webhook.body?.published) return null;
+ *           return webhook;
+ *         },
+ *         onBeforeWebhookTriggered: async ({ batch }) => {
+ *           console.log(`Processing ${batch.webhooks.length} webhooks...`);
+ *           await invalidateCache();
+ *         },
+ *         onAfterWebhookTriggered: async ({ batch }) => {
+ *           await triggerRebuild();
+ *         },
+ *       },
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export interface WebhookHooksConfig {
+  /**
+   * Called when each webhook is received, before queuing.
+   * Return transformed webhook, or null to skip this webhook entirely.
+   * Useful for normalizing webhook shapes from different sources.
+   */
+  onWebhookReceived?: OnWebhookReceivedFn;
+
+  /**
+   * Called before batch processing starts (after debounce period).
+   * Use for cache invalidation, pre-processing, etc.
+   */
+  onBeforeWebhookTriggered?: OnBeforeWebhookTriggeredFn;
+
+  /**
+   * Called after batch processing completes successfully.
+   * Use for triggering rebuilds, notifications, etc.
+   */
+  onAfterWebhookTriggered?: OnAfterWebhookTriggeredFn;
+}
+
+/**
+ * Default webhook hooks (no-op).
+ */
+let webhookHooks: WebhookHooksConfig = {};
+
+/**
+ * Get the current webhook hooks configuration.
+ */
+export function getWebhookHooks(): WebhookHooksConfig {
+  return webhookHooks;
+}
+
+/**
+ * Set the webhook hooks configuration.
+ * Called during server startup with hooks from config.
+ *
+ * @param hooks - The hooks configuration to use
+ */
+export function setWebhookHooks(hooks: WebhookHooksConfig): void {
+  webhookHooks = hooks;
+}
+
+/**
+ * Reset webhook hooks to defaults.
+ * Useful for testing.
+ */
+export function resetWebhookHooks(): void {
+  webhookHooks = {};
+}
diff --git a/packages/core/src/webhooks/index.ts b/packages/core/src/webhooks/index.ts
index b990a22..da8fbc7 100644
--- a/packages/core/src/webhooks/index.ts
+++ b/packages/core/src/webhooks/index.ts
@@ -21,3 +21,40 @@ export {
   defaultWebhookRegistry,
   setDefaultWebhookRegistry,
 } from './registry.js';
+
+// Queue
+export type {
+  QueuedWebhook,
+  WebhookBatch,
+  WebhookQueueConfig,
+  WebhookQueueEvents,
+  BatchProcessorFn,
+} from './queue.js';
+
+export {
+  WebhookQueue,
+  defaultWebhookQueue,
+  setDefaultWebhookQueue,
+} from './queue.js';
+
+// Hooks
+export type {
+  WebhookReceivedContext,
+  WebhookBatchContext,
+  OnWebhookReceivedFn,
+  OnBeforeWebhookTriggeredFn,
+  OnAfterWebhookTriggeredFn,
+  WebhookHooksConfig,
+} from './hooks.js';
+
+export {
+  getWebhookHooks,
+  setWebhookHooks,
+  resetWebhookHooks,
+} from './hooks.js';
+
+// Processor
+export {
+  initializeWebhookProcessor,
+  processWebhookBatch,
+} from './processor.js';
diff --git a/packages/core/src/webhooks/processor.ts b/packages/core/src/webhooks/processor.ts
new file mode 100644
index 0000000..4498f2e
--- /dev/null
+++ b/packages/core/src/webhooks/processor.ts
@@ -0,0 +1,220 @@
+/**
+ * Webhook Batch Processor
+ *
+ * Listens to webhook queue events and invokes the appropriate handlers.
+ * Also runs lifecycle hooks before and after batch processing.
+ */
+
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { EventEmitter } from 'node:events';
+import { defaultWebhookRegistry } from './registry.js';
+import {
+  defaultWebhookQueue,
+  type QueuedWebhook,
+  type WebhookBatch,
+} from './queue.js';
+import { getWebhookHooks } from './hooks.js';
+import { defaultStore } from '@/nodes/defaultStore.js';
+import { createNodeActions } from '@/nodes/actions/index.js';
+import type { WebhookHandlerContext } from './types.js';
+
+/**
+ * Create a minimal mock IncomingMessage for queued webhook processing.
+ * The handler already sent the real HTTP response (202), so this is just
+ * for API compatibility with existing handler signatures.
+ */
+function createMockRequest(webhook: QueuedWebhook): IncomingMessage {
+  const emitter = new EventEmitter();
+  return Object.assign(emitter, {
+    method: 'POST',
+    url: `/_webhooks/${webhook.pluginName}/${webhook.path}`,
+    headers: webhook.headers,
+    httpVersion: '1.1',
+    httpVersionMajor: 1,
+    httpVersionMinor: 1,
+    complete: true,
+    connection: null,
+    socket: null,
+    aborted: false,
+    rawHeaders: [],
+    trailers: {},
+    rawTrailers: [],
+    setTimeout: () => emitter,
+    destroy: () => emitter,
+  }) as unknown as IncomingMessage;
+}
+
+/**
+ * Create a minimal mock ServerResponse for queued webhook processing.
+ * The handler already sent the real HTTP response (202), so this captures
+ * any response the handler tries to send (which will be ignored).
+ */
+function createMockResponse(): ServerResponse {
+  const emitter = new EventEmitter();
+  let headersSent = false;
+
+  return Object.assign(emitter, {
+    statusCode: 200,
+    statusMessage: 'OK',
+    headersSent,
+    get writableEnded() {
+      return headersSent;
+    },
+    writeHead(_statusCode: number, _headers?: Record<string, string>) {
+      headersSent = true;
+      return this;
+    },
+    setHeader: () => emitter,
+    getHeader: () => undefined,
+    removeHeader: () => undefined,
+    write: () => true,
+    end: () => {
+      headersSent = true;
+      return emitter;
+    },
+    flushHeaders: () => undefined,
+    addTrailers: () => undefined,
+    setTimeout: () => emitter,
+    destroy: () => emitter,
+    cork: () => undefined,
+    uncork: () => undefined,
+    assignSocket: () => undefined,
+    detachSocket: () => undefined,
+    writeContinue: () => undefined,
+    writeEarlyHints: () => undefined,
+    writeProcessing: () => undefined,
+  }) as unknown as ServerResponse;
+}
+
+/**
+ * Process a single webhook from the queue.
+ *
+ * @param webhook - The queued webhook to process
+ */
+async function processWebhook(webhook: QueuedWebhook): Promise<void> {
+  const handler = defaultWebhookRegistry.getHandler(
+    webhook.pluginName,
+    webhook.path
+  );
+
+  if (!handler) {
+    console.warn(
+      `⚠️ Handler not found for queued webhook: ${webhook.pluginName}/${webhook.path}`
+    );
+    return;
+  }
+
+  // Create context for the handler
+  const actions = createNodeActions(defaultStore, webhook.pluginName);
+  const context: WebhookHandlerContext = {
+    store: defaultStore,
+    actions,
+    rawBody: webhook.rawBody,
+    body: webhook.body,
+  };
+
+  // Create mock req/res for handler compatibility
+  const mockReq = createMockRequest(webhook);
+  const mockRes = createMockResponse();
+
+  try {
+    await handler.handler(mockReq, mockRes, context);
+  } catch (error) {
+    console.error(
+      `❌ Error processing webhook ${webhook.pluginName}/${webhook.path}:`,
+      error
+    );
+    // Don't rethrow - continue processing other webhooks in the batch
+  }
+}
+
+/**
+ * Initialize the webhook processor.
+ * Sets up event listeners on the default webhook queue.
+ *
+ * This should be called once during server startup.
+ */
+export function initializeWebhookProcessor(): void {
+  // Listen for individual webhook processing
+  defaultWebhookQueue.on('webhook:process', (webhook: QueuedWebhook) => {
+    // Process asynchronously but don't await
+    void processWebhook(webhook);
+  });
+
+  // Listen for batch completion to run hooks
+  defaultWebhookQueue.on(
+    'webhook:batch-complete',
+    async (batch: WebhookBatch) => {
+      const hooks = getWebhookHooks();
+
+      // Run onAfterWebhookTriggered hook
+      if (hooks.onAfterWebhookTriggered) {
+        try {
+          console.log('🪝 Running onAfterWebhookTriggered hook...');
+          await hooks.onAfterWebhookTriggered({
+            batch,
+            store: defaultStore,
+          });
+        } catch (error) {
+          console.error('❌ onAfterWebhookTriggered hook error:', error);
+        }
+      }
+    }
+  );
+
+  // Listen for batch errors
+  defaultWebhookQueue.on(
+    'webhook:batch-error',
+    (error: { webhooks: QueuedWebhook[]; error: Error }) => {
+      console.error(
+        `❌ Batch processing failed for ${error.webhooks.length} webhooks:`,
+        error.error
+      );
+    }
+  );
+
+  console.log('🔗 Webhook processor initialized');
+}
+
+/**
+ * Process a batch of webhooks with lifecycle hooks.
+ * This is called by the queue before emitting individual webhook:process events.
+ *
+ * @param webhooks - The webhooks to process
+ * @returns The processed batch
+ */
+export async function processWebhookBatch(
+  webhooks: QueuedWebhook[]
+): Promise<WebhookBatch> {
+  const startedAt = Date.now();
+  const hooks = getWebhookHooks();
+
+  // Create the batch object
+  const batch: WebhookBatch = {
+    webhooks,
+    startedAt,
+    completedAt: 0,
+  };
+
+  // Run onBeforeWebhookTriggered hook
+  if (hooks.onBeforeWebhookTriggered) {
+    try {
+      console.log('🪝 Running onBeforeWebhookTriggered hook...');
+      await hooks.onBeforeWebhookTriggered({
+        batch,
+        store: defaultStore,
+      });
+    } catch (error) {
+      console.error('❌ onBeforeWebhookTriggered hook error:', error);
+      // Continue processing despite hook error
+    }
+  }
+
+  // Process each webhook
+  for (const webhook of webhooks) {
+    await processWebhook(webhook);
+  }
+
+  batch.completedAt = Date.now();
+  return batch;
+}
diff --git a/packages/core/src/webhooks/queue.ts b/packages/core/src/webhooks/queue.ts
new file mode 100644
index 0000000..e09ea1b
--- /dev/null
+++ b/packages/core/src/webhooks/queue.ts
@@ -0,0 +1,297 @@
+/**
+ * Webhook Queue with Debouncing
+ *
+ * Batches incoming webhooks and processes them after a configurable quiet period.
+ * This prevents N rapid webhook events from triggering N separate processing cycles.
+ */
+
+import { EventEmitter } from 'node:events';
+
+/**
+ * A webhook that has been queued for batch processing.
+ */
+export interface QueuedWebhook {
+  /** Name of the plugin that registered this webhook handler */
+  pluginName: string;
+  /** The webhook path within the plugin */
+  path: string;
+  /** Raw request body buffer */
+  rawBody: Buffer;
+  /** Parsed JSON body (if applicable) */
+  body: unknown;
+  /** Request headers */
+  headers: Record<string, string | string[] | undefined>;
+  /** Timestamp when the webhook was received */
+  timestamp: number;
+}
+
+/**
+ * A batch of webhooks that were processed together.
+ */
+export interface WebhookBatch {
+  /** The webhooks that were processed in this batch */
+  webhooks: QueuedWebhook[];
+  /** Timestamp when batch processing started */
+  startedAt: number;
+  /** Timestamp when batch processing completed */
+  completedAt: number;
+}
+
+/**
+ * Batch processor function type.
+ * Called to process a batch of webhooks with lifecycle hooks.
+ */
+export type BatchProcessorFn = (
+  webhooks: QueuedWebhook[]
+) => Promise<WebhookBatch>;
+
+/**
+ * Configuration options for the webhook queue.
+ */
+export interface WebhookQueueConfig {
+  /**
+   * Debounce period in milliseconds.
+   * After each webhook, the queue waits this long for more webhooks before processing.
+   * @default 5000
+   */
+  debounceMs?: number;
+
+  /**
+   * Maximum queue size before forced processing.
+   * When the queue reaches this size, it will process immediately regardless of debounce.
+   * @default 100
+   */
+  maxQueueSize?: number;
+
+  /**
+   * Custom batch processor function.
+   * If provided, this function is called to process webhooks instead of the default event emission.
+   * This allows for lifecycle hooks integration.
+   */
+  batchProcessor?: BatchProcessorFn;
+}
+
+/**
+ * Events emitted by the WebhookQueue.
+ */
+export interface WebhookQueueEvents {
+  /** Emitted for each webhook when batch processing occurs */
+  'webhook:process': (webhook: QueuedWebhook) => void;
+  /** Emitted after a batch of webhooks has been processed successfully */
+  'webhook:batch-complete': (batch: WebhookBatch) => void;
+  /** Emitted when batch processing encounters an error */
+  'webhook:batch-error': (error: {
+    webhooks: QueuedWebhook[];
+    error: Error;
+  }) => void;
+}
+
+/**
+ * Webhook queue that batches incoming webhooks and processes them after a quiet period.
+ *
+ * @example
+ * ```typescript
+ * const queue = new WebhookQueue({ debounceMs: 5000 });
+ *
+ * queue.on('webhook:process', (webhook) => {
+ *   console.log(`Processing webhook: ${webhook.pluginName}/${webhook.path}`);
+ * });
+ *
+ * queue.on('webhook:batch-complete', (batch) => {
+ *   console.log(`Batch complete: ${batch.webhooks.length} webhooks processed`);
+ * });
+ *
+ * // Webhooks are queued and processed together after 5 seconds of quiet
+ * queue.enqueue(webhook1);
+ * queue.enqueue(webhook2); // Resets the 5 second timer
+ * queue.enqueue(webhook3); // Resets the 5 second timer again
+ * // ... 5 seconds later, all 3 are processed in one batch
+ * ```
+ */
+export class WebhookQueue extends EventEmitter {
+  private queue: QueuedWebhook[] = [];
+  private debounceTimer: NodeJS.Timeout | null = null;
+  private debounceMs: number;
+  private maxQueueSize: number;
+  private isProcessing: boolean = false;
+  private batchProcessor: BatchProcessorFn | undefined;
+
+  constructor(config: WebhookQueueConfig = {}) {
+    super();
+    this.debounceMs = config.debounceMs ?? 5000;
+    this.maxQueueSize = config.maxQueueSize ?? 100;
+    this.batchProcessor = config.batchProcessor ?? undefined;
+  }
+
+  /**
+   * Set the batch processor function.
+   * This is called during server initialization to wire up the processor.
+   *
+   * @param processor - The batch processor function
+   */
+  setBatchProcessor(processor: BatchProcessorFn): void {
+    this.batchProcessor = processor;
+  }
+
+  /**
+   * Add a webhook to the queue. Resets the debounce timer.
+   *
+   * @param webhook - The webhook to queue for processing
+   */
+  enqueue(webhook: QueuedWebhook): void {
+    this.queue.push(webhook);
+    console.log(
+      `📥 Webhook queued: ${webhook.pluginName}/${webhook.path} (${this.queue.length} in queue)`
+    );
+
+    // Check if we've hit max queue size
+    if (this.queue.length >= this.maxQueueSize) {
+      console.log(
+        `📦 Queue reached max size (${this.maxQueueSize}), processing immediately`
+      );
+      if (this.debounceTimer) {
+        clearTimeout(this.debounceTimer);
+        this.debounceTimer = null;
+      }
+      void this.processBatch();
+      return;
+    }
+
+    // Reset debounce timer
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer);
+    }
+
+    this.debounceTimer = setTimeout(() => {
+      void this.processBatch();
+    }, this.debounceMs);
+  }
+
+  /**
+   * Process all queued webhooks as a batch.
+   */
+  private async processBatch(): Promise<void> {
+    if (this.queue.length === 0 || this.isProcessing) {
+      return;
+    }
+
+    this.isProcessing = true;
+    const webhooks = [...this.queue];
+    this.queue = [];
+    this.debounceTimer = null;
+
+    const startedAt = Date.now();
+    console.log(`⚡ Processing webhook batch: ${webhooks.length} webhooks`);
+
+    try {
+      let batch: WebhookBatch;
+
+      if (this.batchProcessor) {
+        // Use the batch processor for full lifecycle hook support
+        batch = await this.batchProcessor(webhooks);
+      } else {
+        // Fallback to event-based processing
+        for (const webhook of webhooks) {
+          this.emit('webhook:process', webhook);
+        }
+
+        const completedAt = Date.now();
+        batch = {
+          webhooks,
+          startedAt,
+          completedAt,
+        };
+      }
+
+      // Emit batch complete event for outbound webhook triggering
+      this.emit('webhook:batch-complete', batch);
+
+      console.log(
+        `✅ Webhook batch complete: ${webhooks.length} processed in ${batch.completedAt - startedAt}ms`
+      );
+    } catch (error) {
+      console.error('❌ Webhook batch processing error:', error);
+      this.emit('webhook:batch-error', {
+        webhooks,
+        error: error instanceof Error ? error : new Error(String(error)),
+      });
+    } finally {
+      this.isProcessing = false;
+    }
+  }
+
+  /**
+   * Get current queue size.
+   *
+   * @returns The number of webhooks currently in the queue
+   */
+  size(): number {
+    return this.queue.length;
+  }
+
+  /**
+   * Check if the queue is currently processing a batch.
+   *
+   * @returns True if batch processing is in progress
+   */
+  processing(): boolean {
+    return this.isProcessing;
+  }
+
+  /**
+   * Force immediate processing of all queued webhooks.
+   * Useful for graceful shutdown to ensure pending webhooks are processed.
+   */
+  async flush(): Promise<void> {
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer);
+      this.debounceTimer = null;
+    }
+    await this.processBatch();
+  }
+
+  /**
+   * Clear all queued webhooks without processing them.
+   * Useful for testing.
+   */
+  clear(): void {
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer);
+      this.debounceTimer = null;
+    }
+    this.queue = [];
+  }
+
+  /**
+   * Get the configured debounce period.
+   *
+   * @returns The debounce period in milliseconds
+   */
+  getDebounceMs(): number {
+    return this.debounceMs;
+  }
+
+  /**
+   * Get the configured maximum queue size.
+   *
+   * @returns The maximum queue size
+   */
+  getMaxQueueSize(): number {
+    return this.maxQueueSize;
+  }
+}
+
+/**
+ * Default singleton webhook queue instance.
+ */
+export let defaultWebhookQueue: WebhookQueue = new WebhookQueue();
+
+/**
+ * Replace the default webhook queue with a new instance.
+ * Useful for testing to ensure isolation between test runs.
+ *
+ * @param queue - The new queue to use as the default
+ */
+export function setDefaultWebhookQueue(queue: WebhookQueue): void {
+  defaultWebhookQueue = queue;
+}
diff --git a/packages/core/tests/integration/webhook-routing.test.ts b/packages/core/tests/integration/webhook-routing.test.ts
index 68341ce..9ea236a 100644
--- a/packages/core/tests/integration/webhook-routing.test.ts
+++ b/packages/core/tests/integration/webhook-routing.test.ts
@@ -8,6 +8,10 @@ import { isWebhookRequest, webhookHandler } from '@/handlers/webhook.js';
 import {
   WebhookRegistry,
   setDefaultWebhookRegistry,
+  WebhookQueue,
+  setDefaultWebhookQueue,
+  resetWebhookHooks,
+  processWebhookBatch,
   type WebhookRegistration,
   type WebhookHandlerContext,
 } from '@/webhooks/index.js';
@@ -108,11 +112,20 @@ describe('webhook routing integration', () => {
     });
   });
 
+  let queue: WebhookQueue;
+
   beforeEach(() => {
     registry = new WebhookRegistry();
     setDefaultWebhookRegistry(registry);
     store = new NodeStore();
     setDefaultStore(store);
+    // Create queue with batch processor that processes immediately
+    queue = new WebhookQueue({
+      debounceMs: 0, // No debounce for tests
+      batchProcessor: processWebhookBatch,
+    });
+    setDefaultWebhookQueue(queue);
+    resetWebhookHooks();
   });
 
   describe('webhook endpoint routing', () => {
@@ -151,7 +164,12 @@ describe('webhook routing integration', () => {
         }
       );
 
-      expect(response.statusCode).toBe(200);
+      // Webhook is queued with 202 response
+      expect(response.statusCode).toBe(202);
+
+      // Flush queue to process the webhook
+      await queue.flush();
+
       expect(handlerCalled).toBe(true);
       expect(receivedBody).toEqual(payload);
     });
@@ -169,7 +187,10 @@ describe('webhook routing integration', () => {
         body: '{}',
       });
 
+      // CORS headers are set by server, not webhook handler
       expect(response.headers['access-control-allow-origin']).toBe('*');
+      // Webhook returns 202 for queued processing
+      expect(response.statusCode).toBe(202);
     });
 
     it('should return 405 for GET requests to webhook endpoints', async () => {
@@ -206,6 +227,9 @@ describe('webhook routing integration', () => {
         body: '{}',
       });
 
+      // Flush queue to process webhook
+      await queue.flush();
+
       expect(receivedContext).toBeDefined();
       expect(receivedContext?.store).toBe(store);
       expect(receivedContext?.actions).toBeDefined();
@@ -231,6 +255,9 @@ describe('webhook routing integration', () => {
         body: JSON.stringify(payload),
       });
 
+      // Flush queue to process webhook
+      await queue.flush();
+
       expect(receivedRawBody).toBeInstanceOf(Buffer);
       expect(receivedRawBody?.toString()).toBe(JSON.stringify(payload));
     });
@@ -267,7 +294,11 @@ describe('webhook routing integration', () => {
         }
       );
 
-      expect(response.statusCode).toBe(200);
+      // Webhook is queued
+      expect(response.statusCode).toBe(202);
+
+      // Flush queue to process webhook
+      await queue.flush();
 
       // Verify node was created in store
       const nodes = store.getAll();
@@ -310,6 +341,9 @@ describe('webhook routing integration', () => {
         body: JSON.stringify({ nodeId: 'node-to-delete' }),
       });
 
+      // Flush queue to process webhook
+      await queue.flush();
+
       // Verify node was deleted
       expect(store.get('node-to-delete')).toBeUndefined();
     });
@@ -341,7 +375,7 @@ describe('webhook routing integration', () => {
       expect(body.error).toBe('Invalid signature');
     });
 
-    it('should call handler when signature is valid', async () => {
+    it('should queue webhook when signature is valid', async () => {
       let handlerCalled = false;
 
       registry.register('secure-plugin', {
@@ -368,7 +402,12 @@ describe('webhook routing integration', () => {
         }
       );
 
-      expect(response.statusCode).toBe(200);
+      // Webhook is queued
+      expect(response.statusCode).toBe(202);
+
+      // Flush queue to process webhook
+      await queue.flush();
+
       expect(handlerCalled).toBe(true);
     });
   });
@@ -395,7 +434,7 @@ describe('webhook routing integration', () => {
       expect(body.error).toBe('Invalid JSON body');
     });
 
-    it('should return 500 when handler throws', async () => {
+    it('should queue webhook even if handler will throw (error happens during batch processing)', async () => {
       registry.register('plugin', {
         path: 'error',
         handler: async () => {
@@ -407,9 +446,13 @@ describe('webhook routing integration', () => {
         body: '{}',
       });
 
-      expect(response.statusCode).toBe(500);
+      // Webhook is queued with 202 - error happens later during batch processing
+      expect(response.statusCode).toBe(202);
       const body = JSON.parse(response.body);
-      expect(body.error).toBe('Internal server error');
+      expect(body.queued).toBe(true);
+
+      // Error is logged during batch processing, not returned to caller
+      // This is expected behavior for async batch processing
     });
   });
 
@@ -437,10 +480,12 @@ describe('webhook routing integration', () => {
 
       // Call plugin-a
       await makeRequest(server, '/_webhooks/plugin-a/update', { body: '{}' });
+      await queue.flush();
       expect(calls).toEqual(['plugin-a']);
 
       // Call plugin-b
       await makeRequest(server, '/_webhooks/plugin-b/update', { body: '{}' });
+      await queue.flush();
       expect(calls).toEqual(['plugin-a', 'plugin-b']);
     });
   });
diff --git a/packages/core/tests/unit/handlers/webhook.test.ts b/packages/core/tests/unit/handlers/webhook.test.ts
index 173030f..209c00e 100644
--- a/packages/core/tests/unit/handlers/webhook.test.ts
+++ b/packages/core/tests/unit/handlers/webhook.test.ts
@@ -10,8 +10,12 @@ import {
 import {
   WebhookRegistry,
   setDefaultWebhookRegistry,
+  WebhookQueue,
+  setDefaultWebhookQueue,
+  resetWebhookHooks,
+  setWebhookHooks,
   type WebhookRegistration,
-  type WebhookHandlerContext,
+  type QueuedWebhook,
 } from '@/webhooks/index.js';
 
 // Create a mock request that extends EventEmitter to support .on() calls
@@ -170,10 +174,14 @@ describe('WEBHOOK_PATH_PREFIX', () => {
 
 describe('webhookHandler', () => {
   let registry: WebhookRegistry;
+  let queue: WebhookQueue;
 
   beforeEach(() => {
     registry = new WebhookRegistry();
     setDefaultWebhookRegistry(registry);
+    queue = new WebhookQueue({ debounceMs: 5000 });
+    setDefaultWebhookQueue(queue);
+    resetWebhookHooks();
   });
 
   describe('HTTP method validation', () => {
@@ -311,21 +319,15 @@ describe('webhookHandler', () => {
       consoleErrorSpy.mockRestore();
     });
 
-    it('should call handler when verifySignature returns true', async () => {
+    it('should queue webhook when verifySignature returns true', async () => {
       const consoleLogSpy = vi
         .spyOn(console, 'log')
         .mockImplementation(() => {});
-      const handlerCalled = vi.fn();
 
       registry.register(
         'plugin',
         createTestWebhook('path', {
           verifySignature: () => true,
-          handler: async (_req, res, _context) => {
-            handlerCalled();
-            res.writeHead(200);
-            res.end('OK');
-          },
         })
       );
 
@@ -335,8 +337,9 @@ describe('webhookHandler', () => {
       emitBody(req, '{}');
       await webhookHandler(req, res);
 
-      expect(res._statusCode).toBe(200);
-      expect(handlerCalled).toHaveBeenCalled();
+      // Webhook is queued, not immediately processed
+      expect(res._statusCode).toBe(202);
+      expect(queue.size()).toBe(1);
 
       consoleLogSpy.mockRestore();
     });
@@ -362,7 +365,9 @@ describe('webhookHandler', () => {
       emitBody(req, '{}');
       await webhookHandler(req, res);
 
-      expect(res._statusCode).toBe(200);
+      // Webhook is queued after signature verification
+      expect(res._statusCode).toBe(202);
+      expect(queue.size()).toBe(1);
 
       consoleLogSpy.mockRestore();
     });
@@ -380,7 +385,9 @@ describe('webhookHandler', () => {
       emitBody(req, '{}');
       await webhookHandler(req, res);
 
-      expect(res._statusCode).toBe(200);
+      // Webhook is queued without signature verification
+      expect(res._statusCode).toBe(202);
+      expect(queue.size()).toBe(1);
 
       consoleLogSpy.mockRestore();
     });
@@ -403,22 +410,20 @@ describe('webhookHandler', () => {
       expect(body.error).toBe('Invalid JSON body');
     });
 
-    it('should parse valid JSON body', async () => {
+    it('should queue webhook with parsed JSON body', async () => {
       const consoleLogSpy = vi
         .spyOn(console, 'log')
         .mockImplementation(() => {});
-      let receivedContext: WebhookHandlerContext | undefined;
+      let queuedWebhook: QueuedWebhook | undefined;
 
-      registry.register(
-        'plugin',
-        createTestWebhook('path', {
-          handler: async (_req, res, context) => {
-            receivedContext = context;
-            res.writeHead(200);
-            res.end('OK');
-          },
-        })
-      );
+      // Listen for enqueue
+      const originalEnqueue = queue.enqueue.bind(queue);
+      queue.enqueue = (webhook: QueuedWebhook) => {
+        queuedWebhook = webhook;
+        originalEnqueue(webhook);
+      };
+
+      registry.register('plugin', createTestWebhook('path'));
 
       const req = createMockRequest('POST', '/_webhooks/plugin/path', {
         'content-type': 'application/json',
@@ -429,28 +434,26 @@ describe('webhookHandler', () => {
       emitBody(req, JSON.stringify(payload));
       await webhookHandler(req, res);
 
-      expect(res._statusCode).toBe(200);
-      expect(receivedContext?.body).toEqual(payload);
+      expect(res._statusCode).toBe(202);
+      expect(queuedWebhook?.body).toEqual(payload);
 
       consoleLogSpy.mockRestore();
     });
 
-    it('should pass undefined body for non-JSON content types', async () => {
+    it('should queue webhook with undefined body for non-JSON content types', async () => {
       const consoleLogSpy = vi
         .spyOn(console, 'log')
         .mockImplementation(() => {});
-      let receivedContext: WebhookHandlerContext | undefined;
+      let queuedWebhook: QueuedWebhook | undefined;
 
-      registry.register(
-        'plugin',
-        createTestWebhook('path', {
-          handler: async (_req, res, context) => {
-            receivedContext = context;
-            res.writeHead(200);
-            res.end('OK');
-          },
-        })
-      );
+      // Listen for enqueue
+      const originalEnqueue = queue.enqueue.bind(queue);
+      queue.enqueue = (webhook: QueuedWebhook) => {
+        queuedWebhook = webhook;
+        originalEnqueue(webhook);
+      };
+
+      registry.register('plugin', createTestWebhook('path'));
 
       const req = createMockRequest('POST', '/_webhooks/plugin/path', {
         'content-type': 'text/plain',
@@ -460,28 +463,26 @@ describe('webhookHandler', () => {
       emitBody(req, 'plain text body');
       await webhookHandler(req, res);
 
-      expect(res._statusCode).toBe(200);
-      expect(receivedContext?.body).toBeUndefined();
+      expect(res._statusCode).toBe(202);
+      expect(queuedWebhook?.body).toBeUndefined();
 
       consoleLogSpy.mockRestore();
     });
 
-    it('should always pass rawBody buffer', async () => {
+    it('should queue webhook with rawBody buffer', async () => {
       const consoleLogSpy = vi
         .spyOn(console, 'log')
         .mockImplementation(() => {});
-      let receivedContext: WebhookHandlerContext | undefined;
+      let queuedWebhook: QueuedWebhook | undefined;
 
-      registry.register(
-        'plugin',
-        createTestWebhook('path', {
-          handler: async (_req, res, context) => {
-            receivedContext = context;
-            res.writeHead(200);
-            res.end('OK');
-          },
-        })
-      );
+      // Listen for enqueue
+      const originalEnqueue = queue.enqueue.bind(queue);
+      queue.enqueue = (webhook: QueuedWebhook) => {
+        queuedWebhook = webhook;
+        originalEnqueue(webhook);
+      };
+
+      registry.register('plugin', createTestWebhook('path'));
 
       const req = createMockRequest('POST', '/_webhooks/plugin/path');
       const res = createMockResponse();
@@ -490,31 +491,29 @@ describe('webhookHandler', () => {
       emitBody(req, bodyText);
       await webhookHandler(req, res);
 
-      expect(res._statusCode).toBe(200);
-      expect(receivedContext?.rawBody).toBeInstanceOf(Buffer);
-      expect(receivedContext?.rawBody.toString()).toBe(bodyText);
+      expect(res._statusCode).toBe(202);
+      expect(queuedWebhook?.rawBody).toBeInstanceOf(Buffer);
+      expect(queuedWebhook?.rawBody.toString()).toBe(bodyText);
 
       consoleLogSpy.mockRestore();
     });
   });
 
-  describe('handler execution', () => {
-    it('should call handler with correct context', async () => {
+  describe('webhook queuing', () => {
+    it('should queue webhook with correct metadata', async () => {
       const consoleLogSpy = vi
         .spyOn(console, 'log')
         .mockImplementation(() => {});
-      let receivedContext: WebhookHandlerContext | undefined;
+      let queuedWebhook: QueuedWebhook | undefined;
 
-      registry.register(
-        'test-plugin',
-        createTestWebhook('update', {
-          handler: async (_req, res, context) => {
-            receivedContext = context;
-            res.writeHead(200);
-            res.end('OK');
-          },
-        })
-      );
+      // Listen for enqueue
+      const originalEnqueue = queue.enqueue.bind(queue);
+      queue.enqueue = (webhook: QueuedWebhook) => {
+        queuedWebhook = webhook;
+        originalEnqueue(webhook);
+      };
+
+      registry.register('test-plugin', createTestWebhook('update'));
 
       const req = createMockRequest('POST', '/_webhooks/test-plugin/update', {
         'content-type': 'application/json',
@@ -524,33 +523,23 @@ describe('webhookHandler', () => {
       emitBody(req, '{"test": true}');
       await webhookHandler(req, res);
 
-      expect(receivedContext).toBeDefined();
-      expect(receivedContext?.store).toBeDefined();
-      expect(receivedContext?.actions).toBeDefined();
-      expect(receivedContext?.actions.createNode).toBeDefined();
-      expect(receivedContext?.actions.deleteNode).toBeDefined();
-      expect(receivedContext?.rawBody).toBeInstanceOf(Buffer);
-      expect(receivedContext?.body).toEqual({ test: true });
+      expect(res._statusCode).toBe(202);
+      expect(queuedWebhook).toBeDefined();
+      expect(queuedWebhook?.pluginName).toBe('test-plugin');
+      expect(queuedWebhook?.path).toBe('update');
+      expect(queuedWebhook?.body).toEqual({ test: true });
+      expect(queuedWebhook?.rawBody).toBeInstanceOf(Buffer);
+      expect(queuedWebhook?.timestamp).toBeGreaterThan(0);
 
       consoleLogSpy.mockRestore();
     });
 
-    it('should return 500 when handler throws', async () => {
+    it('should return 202 with queued response', async () => {
       const consoleLogSpy = vi
         .spyOn(console, 'log')
         .mockImplementation(() => {});
-      const consoleErrorSpy = vi
-        .spyOn(console, 'error')
-        .mockImplementation(() => {});
 
-      registry.register(
-        'plugin',
-        createTestWebhook('path', {
-          handler: async () => {
-            throw new Error('Handler error');
-          },
-        })
-      );
+      registry.register('plugin', createTestWebhook('path'));
 
       const req = createMockRequest('POST', '/_webhooks/plugin/path');
       const res = createMockResponse();
@@ -558,62 +547,103 @@ describe('webhookHandler', () => {
       emitBody(req, '{}');
       await webhookHandler(req, res);
 
-      expect(res._statusCode).toBe(500);
+      expect(res._statusCode).toBe(202);
       const body = JSON.parse(res._body);
-      expect(body.error).toBe('Internal server error');
-      expect(consoleErrorSpy).toHaveBeenCalled();
+      expect(body.queued).toBe(true);
 
       consoleLogSpy.mockRestore();
-      consoleErrorSpy.mockRestore();
     });
 
-    it('should not send error response if headers already sent', async () => {
+    it('should log webhook received message', async () => {
       const consoleLogSpy = vi
         .spyOn(console, 'log')
         .mockImplementation(() => {});
-      const consoleErrorSpy = vi
-        .spyOn(console, 'error')
-        .mockImplementation(() => {});
 
-      registry.register(
-        'plugin',
-        createTestWebhook('path', {
-          handler: async (_req, res) => {
-            res.writeHead(202);
-            res.end('Accepted');
-            throw new Error('Post-response error');
-          },
-        })
+      registry.register('my-plugin', createTestWebhook('my-path'));
+
+      const req = createMockRequest('POST', '/_webhooks/my-plugin/my-path');
+      const res = createMockResponse();
+
+      emitBody(req, '{}');
+      await webhookHandler(req, res);
+
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        'Webhook received: my-plugin/my-path'
       );
 
+      consoleLogSpy.mockRestore();
+    });
+
+    it('should include headers in queued webhook', async () => {
+      const consoleLogSpy = vi
+        .spyOn(console, 'log')
+        .mockImplementation(() => {});
+      let queuedWebhook: QueuedWebhook | undefined;
+
+      // Listen for enqueue
+      const originalEnqueue = queue.enqueue.bind(queue);
+      queue.enqueue = (webhook: QueuedWebhook) => {
+        queuedWebhook = webhook;
+        originalEnqueue(webhook);
+      };
+
+      registry.register('plugin', createTestWebhook('path'));
+
+      const req = createMockRequest('POST', '/_webhooks/plugin/path', {
+        'content-type': 'application/json',
+        'x-custom-header': 'custom-value',
+      });
+      const res = createMockResponse();
+
+      emitBody(req, '{}');
+      await webhookHandler(req, res);
+
+      expect(res._statusCode).toBe(202);
+      expect(queuedWebhook?.headers['content-type']).toBe('application/json');
+      expect(queuedWebhook?.headers['x-custom-header']).toBe('custom-value');
+
+      consoleLogSpy.mockRestore();
+    });
+  });
+
+  describe('onWebhookReceived hook', () => {
+    it('should call onWebhookReceived hook when configured', async () => {
+      const consoleLogSpy = vi
+        .spyOn(console, 'log')
+        .mockImplementation(() => {});
+      const hookCalled = vi.fn();
+
+      setWebhookHooks({
+        onWebhookReceived: async ({ webhook }) => {
+          hookCalled(webhook);
+          return webhook;
+        },
+      });
+
+      registry.register('plugin', createTestWebhook('path'));
+
       const req = createMockRequest('POST', '/_webhooks/plugin/path');
       const res = createMockResponse();
 
       emitBody(req, '{}');
       await webhookHandler(req, res);
 
-      // Should keep the 202 status, not override with 500
+      expect(hookCalled).toHaveBeenCalled();
       expect(res._statusCode).toBe(202);
-      expect(res._body).toBe('Accepted');
 
       consoleLogSpy.mockRestore();
-      consoleErrorSpy.mockRestore();
     });
 
-    it('should allow handler to set custom response', async () => {
+    it('should skip webhook when onWebhookReceived returns null', async () => {
       const consoleLogSpy = vi
         .spyOn(console, 'log')
         .mockImplementation(() => {});
 
-      registry.register(
-        'plugin',
-        createTestWebhook('path', {
-          handler: async (_req, res) => {
-            res.writeHead(201, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({ status: 'created' }));
-          },
-        })
-      );
+      setWebhookHooks({
+        onWebhookReceived: async () => null,
+      });
+
+      registry.register('plugin', createTestWebhook('path'));
 
       const req = createMockRequest('POST', '/_webhooks/plugin/path');
       const res = createMockResponse();
@@ -621,31 +651,92 @@ describe('webhookHandler', () => {
       emitBody(req, '{}');
       await webhookHandler(req, res);
 
-      expect(res._statusCode).toBe(201);
+      expect(res._statusCode).toBe(200);
       const body = JSON.parse(res._body);
-      expect(body.status).toBe('created');
+      expect(body.skipped).toBe(true);
+      expect(queue.size()).toBe(0);
 
       consoleLogSpy.mockRestore();
     });
 
-    it('should log webhook received message', async () => {
+    it('should use transformed webhook from onWebhookReceived', async () => {
       const consoleLogSpy = vi
         .spyOn(console, 'log')
         .mockImplementation(() => {});
+      let queuedWebhook: QueuedWebhook | undefined;
 
-      registry.register('my-plugin', createTestWebhook('my-path'));
+      // Listen for enqueue
+      const originalEnqueue = queue.enqueue.bind(queue);
+      queue.enqueue = (webhook: QueuedWebhook) => {
+        queuedWebhook = webhook;
+        originalEnqueue(webhook);
+      };
 
-      const req = createMockRequest('POST', '/_webhooks/my-plugin/my-path');
+      setWebhookHooks({
+        onWebhookReceived: async ({ webhook }) => ({
+          ...webhook,
+          body: { transformed: true, original: webhook.body },
+        }),
+      });
+
+      registry.register('plugin', createTestWebhook('path'));
+
+      const req = createMockRequest('POST', '/_webhooks/plugin/path', {
+        'content-type': 'application/json',
+      });
       const res = createMockResponse();
 
-      emitBody(req, '{}');
+      emitBody(req, '{"original": "data"}');
       await webhookHandler(req, res);
 
-      expect(consoleLogSpy).toHaveBeenCalledWith(
-        'Webhook received: my-plugin/my-path'
-      );
+      expect(res._statusCode).toBe(202);
+      expect(queuedWebhook?.body).toEqual({
+        transformed: true,
+        original: { original: 'data' },
+      });
+
+      consoleLogSpy.mockRestore();
+    });
+
+    it('should continue with original webhook if onWebhookReceived throws', async () => {
+      const consoleLogSpy = vi
+        .spyOn(console, 'log')
+        .mockImplementation(() => {});
+      const consoleErrorSpy = vi
+        .spyOn(console, 'error')
+        .mockImplementation(() => {});
+      let queuedWebhook: QueuedWebhook | undefined;
+
+      // Listen for enqueue
+      const originalEnqueue = queue.enqueue.bind(queue);
+      queue.enqueue = (webhook: QueuedWebhook) => {
+        queuedWebhook = webhook;
+        originalEnqueue(webhook);
+      };
+
+      setWebhookHooks({
+        onWebhookReceived: async () => {
+          throw new Error('Hook error');
+        },
+      });
+
+      registry.register('plugin', createTestWebhook('path'));
+
+      const req = createMockRequest('POST', '/_webhooks/plugin/path', {
+        'content-type': 'application/json',
+      });
+      const res = createMockResponse();
+
+      emitBody(req, '{"test": true}');
+      await webhookHandler(req, res);
+
+      // Should still queue the original webhook
+      expect(res._statusCode).toBe(202);
+      expect(queuedWebhook?.body).toEqual({ test: true });
+      expect(consoleErrorSpy).toHaveBeenCalled();
 
       consoleLogSpy.mockRestore();
+      consoleErrorSpy.mockRestore();
     });
   });
 
diff --git a/packages/core/tests/unit/webhooks/queue.test.ts b/packages/core/tests/unit/webhooks/queue.test.ts
new file mode 100644
index 0000000..5d03003
--- /dev/null
+++ b/packages/core/tests/unit/webhooks/queue.test.ts
@@ -0,0 +1,409 @@
+import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest';
+import {
+  WebhookQueue,
+  setDefaultWebhookQueue,
+  type QueuedWebhook,
+  type WebhookBatch,
+} from '@/webhooks/index.js';
+
+// Helper to create a mock webhook
+function createMockWebhook(
+  pluginName: string,
+  path: string,
+  body?: unknown
+): QueuedWebhook {
+  return {
+    pluginName,
+    path,
+    rawBody: Buffer.from(JSON.stringify(body ?? {})),
+    body: body ?? {},
+    headers: { 'content-type': 'application/json' },
+    timestamp: Date.now(),
+  };
+}
+
+describe('WebhookQueue', () => {
+  let queue: WebhookQueue;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    queue = new WebhookQueue({ debounceMs: 5000, maxQueueSize: 100 });
+    setDefaultWebhookQueue(queue);
+
+    // Suppress console logs
+    vi.spyOn(console, 'log').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+    queue.clear();
+  });
+
+  describe('constructor', () => {
+    it('should use default debounceMs of 5000', () => {
+      const defaultQueue = new WebhookQueue();
+      expect(defaultQueue.getDebounceMs()).toBe(5000);
+    });
+
+    it('should use default maxQueueSize of 100', () => {
+      const defaultQueue = new WebhookQueue();
+      expect(defaultQueue.getMaxQueueSize()).toBe(100);
+    });
+
+    it('should accept custom debounceMs', () => {
+      const customQueue = new WebhookQueue({ debounceMs: 10000 });
+      expect(customQueue.getDebounceMs()).toBe(10000);
+    });
+
+    it('should accept custom maxQueueSize', () => {
+      const customQueue = new WebhookQueue({ maxQueueSize: 50 });
+      expect(customQueue.getMaxQueueSize()).toBe(50);
+    });
+  });
+
+  describe('enqueue', () => {
+    it('should add webhook to queue', () => {
+      const webhook = createMockWebhook('plugin', 'path');
+      queue.enqueue(webhook);
+      expect(queue.size()).toBe(1);
+    });
+
+    it('should increment queue size with each enqueue', () => {
+      queue.enqueue(createMockWebhook('plugin', 'path-1'));
+      queue.enqueue(createMockWebhook('plugin', 'path-2'));
+      queue.enqueue(createMockWebhook('plugin', 'path-3'));
+      expect(queue.size()).toBe(3);
+    });
+
+    it('should start debounce timer on first enqueue', () => {
+      const webhook = createMockWebhook('plugin', 'path');
+      queue.enqueue(webhook);
+
+      // Queue should not be processed yet
+      expect(queue.size()).toBe(1);
+
+      // Advance timer by 4999ms (just before debounce)
+      vi.advanceTimersByTime(4999);
+      expect(queue.size()).toBe(1);
+
+      // Advance timer by 1ms to trigger processing
+      vi.advanceTimersByTime(1);
+      expect(queue.size()).toBe(0);
+    });
+
+    it('should reset debounce timer on each enqueue', () => {
+      queue.enqueue(createMockWebhook('plugin', 'path-1'));
+
+      // Advance timer by 4000ms
+      vi.advanceTimersByTime(4000);
+      expect(queue.size()).toBe(1);
+
+      // Enqueue another webhook - should reset timer
+      queue.enqueue(createMockWebhook('plugin', 'path-2'));
+
+      // Advance timer by 4000ms again (total 8000ms since first enqueue)
+      vi.advanceTimersByTime(4000);
+      expect(queue.size()).toBe(2); // Still queued because timer was reset
+
+      // Advance timer by 1000ms more (5000ms since second enqueue)
+      vi.advanceTimersByTime(1000);
+      expect(queue.size()).toBe(0); // Processed now
+    });
+  });
+
+  describe('batch processing', () => {
+    it('should emit webhook:process for each webhook in batch', async () => {
+      const processedWebhooks: QueuedWebhook[] = [];
+      queue.on('webhook:process', (webhook: QueuedWebhook) => {
+        processedWebhooks.push(webhook);
+      });
+
+      queue.enqueue(createMockWebhook('plugin', 'path-1'));
+      queue.enqueue(createMockWebhook('plugin', 'path-2'));
+      queue.enqueue(createMockWebhook('plugin', 'path-3'));
+
+      vi.advanceTimersByTime(5000);
+
+      expect(processedWebhooks.length).toBe(3);
+      expect(processedWebhooks[0]?.path).toBe('path-1');
+      expect(processedWebhooks[1]?.path).toBe('path-2');
+      expect(processedWebhooks[2]?.path).toBe('path-3');
+    });
+
+    it('should emit webhook:batch-complete after processing', async () => {
+      let completedBatch: WebhookBatch | undefined;
+      queue.on('webhook:batch-complete', (batch: WebhookBatch) => {
+        completedBatch = batch;
+      });
+
+      queue.enqueue(createMockWebhook('plugin', 'path-1'));
+      queue.enqueue(createMockWebhook('plugin', 'path-2'));
+
+      vi.advanceTimersByTime(5000);
+
+      expect(completedBatch).toBeDefined();
+      expect(completedBatch?.webhooks.length).toBe(2);
+      expect(completedBatch?.startedAt).toBeGreaterThan(0);
+      expect(completedBatch?.completedAt).toBeGreaterThanOrEqual(
+        completedBatch!.startedAt
+      );
+    });
+
+    it('should batch all queued webhooks into single processing', async () => {
+      let batchCount = 0;
+      queue.on('webhook:batch-complete', () => {
+        batchCount++;
+      });
+
+      // Enqueue 10 webhooks rapidly
+      for (let i = 0; i < 10; i++) {
+        queue.enqueue(createMockWebhook('plugin', `path-${i}`));
+      }
+
+      vi.advanceTimersByTime(5000);
+
+      // Should only have 1 batch
+      expect(batchCount).toBe(1);
+    });
+
+    it('should process immediately when max queue size is reached', async () => {
+      const smallQueue = new WebhookQueue({
+        debounceMs: 5000,
+        maxQueueSize: 5,
+      });
+
+      let batchCount = 0;
+      smallQueue.on('webhook:batch-complete', () => {
+        batchCount++;
+      });
+
+      // Enqueue 5 webhooks (max size)
+      for (let i = 0; i < 5; i++) {
+        smallQueue.enqueue(createMockWebhook('plugin', `path-${i}`));
+      }
+
+      // Should process immediately without waiting for debounce
+      expect(smallQueue.size()).toBe(0);
+      expect(batchCount).toBe(1);
+    });
+  });
+
+  describe('flush', () => {
+    it('should process queued webhooks immediately', async () => {
+      queue.enqueue(createMockWebhook('plugin', 'path-1'));
+      queue.enqueue(createMockWebhook('plugin', 'path-2'));
+
+      expect(queue.size()).toBe(2);
+
+      await queue.flush();
+
+      expect(queue.size()).toBe(0);
+    });
+
+    it('should clear debounce timer', async () => {
+      queue.enqueue(createMockWebhook('plugin', 'path-1'));
+
+      // Advance timer partially
+      vi.advanceTimersByTime(2000);
+
+      await queue.flush();
+
+      // Advance timer past original debounce time
+      vi.advanceTimersByTime(5000);
+
+      // Should not process again (no duplicate processing)
+      expect(queue.size()).toBe(0);
+    });
+
+    it('should emit batch-complete event', async () => {
+      let completed = false;
+      queue.on('webhook:batch-complete', () => {
+        completed = true;
+      });
+
+      queue.enqueue(createMockWebhook('plugin', 'path-1'));
+      await queue.flush();
+
+      expect(completed).toBe(true);
+    });
+
+    it('should do nothing if queue is empty', async () => {
+      let completed = false;
+      queue.on('webhook:batch-complete', () => {
+        completed = true;
+      });
+
+      await queue.flush();
+
+      expect(completed).toBe(false);
+    });
+  });
+
+  describe('clear', () => {
+    it('should remove all queued webhooks', () => {
+      queue.enqueue(createMockWebhook('plugin', 'path-1'));
+      queue.enqueue(createMockWebhook('plugin', 'path-2'));
+
+      expect(queue.size()).toBe(2);
+
+      queue.clear();
+
+      expect(queue.size()).toBe(0);
+    });
+
+    it('should clear debounce timer', () => {
+      queue.enqueue(createMockWebhook('plugin', 'path-1'));
+
+      queue.clear();
+
+      // Advance timer past debounce time
+      vi.advanceTimersByTime(10000);
+
+      // No processing should occur
+      expect(queue.size()).toBe(0);
+    });
+  });
+
+  describe('size', () => {
+    it('should return 0 for empty queue', () => {
+      expect(queue.size()).toBe(0);
+    });
+
+    it('should return correct count after enqueue', () => {
+      queue.enqueue(createMockWebhook('plugin', 'path-1'));
+      expect(queue.size()).toBe(1);
+
+      queue.enqueue(createMockWebhook('plugin', 'path-2'));
+      expect(queue.size()).toBe(2);
+    });
+
+    it('should return 0 after processing', () => {
+      queue.enqueue(createMockWebhook('plugin', 'path-1'));
+      vi.advanceTimersByTime(5000);
+      expect(queue.size()).toBe(0);
+    });
+  });
+
+  describe('processing', () => {
+    it('should return false when not processing', () => {
+      expect(queue.processing()).toBe(false);
+    });
+
+    it('should not process if already processing', async () => {
+      let processCount = 0;
+
+      // Use a custom batch processor that tracks calls
+      const slowQueue = new WebhookQueue({
+        debounceMs: 1000,
+        batchProcessor: async (webhooks) => {
+          processCount++;
+          // Simulate slow processing
+          await new Promise((resolve) => setTimeout(resolve, 100));
+          return {
+            webhooks,
+            startedAt: Date.now(),
+            completedAt: Date.now(),
+          };
+        },
+      });
+
+      slowQueue.enqueue(createMockWebhook('plugin', 'path-1'));
+
+      // Trigger processing
+      vi.advanceTimersByTime(1000);
+
+      // Try to flush while processing (should be skipped)
+      await slowQueue.flush();
+
+      // Should only have processed once
+      expect(processCount).toBe(1);
+    });
+  });
+
+  describe('setBatchProcessor', () => {
+    it('should use custom batch processor', async () => {
+      let processedWebhooks: QueuedWebhook[] = [];
+
+      queue.setBatchProcessor(async (webhooks) => {
+        processedWebhooks = webhooks;
+        return {
+          webhooks,
+          startedAt: Date.now(),
+          completedAt: Date.now(),
+        };
+      });
+
+      queue.enqueue(createMockWebhook('plugin', 'path-1'));
+      queue.enqueue(createMockWebhook('plugin', 'path-2'));
+
+      await queue.flush();
+
+      expect(processedWebhooks.length).toBe(2);
+    });
+
+    it('should not emit webhook:process when using custom processor', async () => {
+      let processEventCount = 0;
+      queue.on('webhook:process', () => {
+        processEventCount++;
+      });
+
+      queue.setBatchProcessor(async (webhooks) => ({
+        webhooks,
+        startedAt: Date.now(),
+        completedAt: Date.now(),
+      }));
+
+      queue.enqueue(createMockWebhook('plugin', 'path-1'));
+      await queue.flush();
+
+      // Custom processor handles processing, so no events emitted
+      expect(processEventCount).toBe(0);
+    });
+  });
+
+  describe('error handling', () => {
+    it('should emit webhook:batch-error when processing fails', async () => {
+      let receivedError:
+        | { webhooks: QueuedWebhook[]; error: Error }
+        | undefined;
+
+      const consoleErrorSpy = vi
+        .spyOn(console, 'error')
+        .mockImplementation(() => {});
+
+      queue.setBatchProcessor(async () => {
+        throw new Error('Processing failed');
+      });
+
+      queue.on(
+        'webhook:batch-error',
+        (error: { webhooks: QueuedWebhook[]; error: Error }) => {
+          receivedError = error;
+        }
+      );
+
+      queue.enqueue(createMockWebhook('plugin', 'path-1'));
+      await queue.flush();
+
+      expect(receivedError).toBeDefined();
+      expect(receivedError?.error.message).toBe('Processing failed');
+      expect(receivedError?.webhooks.length).toBe(1);
+
+      consoleErrorSpy.mockRestore();
+    });
+
+    it('should set isProcessing to false after error', async () => {
+      vi.spyOn(console, 'error').mockImplementation(() => {});
+
+      queue.setBatchProcessor(async () => {
+        throw new Error('Processing failed');
+      });
+
+      queue.enqueue(createMockWebhook('plugin', 'path-1'));
+      await queue.flush();
+
+      expect(queue.processing()).toBe(false);
+    });
+  });
+});

From 16ab7d81ee9c0610933b180aa12eeed6d41d660a Mon Sep 17 00:00:00 2001
From: dawidurbanski <hi@dawidurbanski.com>
Date: Sun, 21 Dec 2025 23:45:06 +0100
Subject: [PATCH 07/46] feat(core): add outbound webhook triggering after batch
 processing
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add OutboundWebhookManager to notify external systems (e.g., Vercel deploy
hooks, CI systems) after webhook batches are processed. This enables the
"30 webhooks → 1 build" optimization.

Features:
- Configurable outbound endpoints via remote.webhooks.trigger
- Retry logic with exponential backoff (default: 3 retries)
- Custom headers support for authentication
- Parallel triggering to multiple endpoints
- Payload includes batch summary (webhookCount, plugins, timestamp)
---
 .changeset/outbound-webhook-triggering.md     |  53 ++
 packages/core/src/loader.ts                   |  45 ++
 packages/core/src/start-server.ts             |  13 +
 packages/core/src/webhooks/index.ts           |   9 +
 packages/core/src/webhooks/outbound.ts        | 245 +++++++++
 .../tests/integration/webhook-routing.test.ts | 252 +++++++++-
 .../core/tests/unit/webhooks/outbound.test.ts | 465 ++++++++++++++++++
 7 files changed, 1081 insertions(+), 1 deletion(-)
 create mode 100644 .changeset/outbound-webhook-triggering.md
 create mode 100644 packages/core/src/webhooks/outbound.ts
 create mode 100644 packages/core/tests/unit/webhooks/outbound.test.ts

diff --git a/.changeset/outbound-webhook-triggering.md b/.changeset/outbound-webhook-triggering.md
new file mode 100644
index 0000000..674d9bd
--- /dev/null
+++ b/.changeset/outbound-webhook-triggering.md
@@ -0,0 +1,53 @@
+---
+'universal-data-layer': minor
+---
+
+Add outbound webhook triggering after batch processing
+
+This release adds the ability to trigger outbound webhooks after a batch of incoming webhooks has been processed. This enables the "30 webhooks → 1 build" optimization by notifying external systems (e.g., Vercel deploy hooks, CI systems) once after processing a batch rather than for each individual webhook.
+
+**Features:**
+
+- `OutboundWebhookManager` class for managing outbound webhook notifications
+- Configurable outbound webhook endpoints via `remote.webhooks.trigger`
+- Retry logic with exponential backoff (default: 3 retries, 1000ms base delay)
+- Custom headers support for authentication
+- Parallel triggering to multiple endpoints using `Promise.allSettled`
+- Payload includes batch summary: webhook count, plugins, timestamp, source
+
+**Example configuration:**
+
+```typescript
+export const { config } = defineConfig({
+  remote: {
+    webhooks: {
+      debounceMs: 5000,
+      trigger: [
+        {
+          url: 'https://api.vercel.com/v1/integrations/deploy/...',
+          headers: { Authorization: 'Bearer token' },
+          retries: 3,
+          retryDelayMs: 1000,
+        },
+        {
+          url: 'https://my-ci.example.com/webhook',
+        },
+      ],
+    },
+  },
+});
+```
+
+**Outbound webhook payload:**
+
+```json
+{
+  "event": "batch-complete",
+  "timestamp": "2024-01-15T10:30:00.000Z",
+  "summary": {
+    "webhookCount": 30,
+    "plugins": ["@universal-data-layer/plugin-source-contentful"]
+  },
+  "source": "default"
+}
+```
diff --git a/packages/core/src/loader.ts b/packages/core/src/loader.ts
index 0b2db52..c83cd33 100644
--- a/packages/core/src/loader.ts
+++ b/packages/core/src/loader.ts
@@ -84,6 +84,33 @@ export interface CodegenConfig {
   )[];
 }
 
+/**
+ * Configuration for an outbound webhook trigger.
+ * Outbound webhooks are sent after batch processing to notify external systems.
+ */
+export interface OutboundWebhookTriggerConfig {
+  /** URL to POST to */
+  url: string;
+  /**
+   * Events to trigger on. '*' = all events.
+   * @default ['*']
+   */
+  events?: string[];
+  /** Custom headers to include in the request */
+  headers?: Record<string, string>;
+  /**
+   * Number of retries on failure.
+   * @default 3
+   */
+  retries?: number;
+  /**
+   * Base delay between retries in milliseconds.
+   * Uses exponential backoff: retryDelayMs * (attempt + 1)
+   * @default 1000
+   */
+  retryDelayMs?: number;
+}
+
 /**
  * Configuration for remote webhook handling.
  */
@@ -106,6 +133,24 @@ export interface RemoteWebhooksConfig {
    * Lifecycle hooks for webhook processing.
    */
   hooks?: WebhookHooksConfig;
+
+  /**
+   * Outbound webhook triggers to notify after batch processing.
+   * These webhooks are sent after a batch of incoming webhooks has been processed,
+   * enabling the "30 webhooks → 1 build" optimization.
+   *
+   * @example
+   * ```typescript
+   * trigger: [
+   *   {
+   *     url: 'https://api.vercel.com/v1/integrations/deploy/...',
+   *     headers: { 'Authorization': 'Bearer token' },
+   *     retries: 3,
+   *   }
+   * ]
+   * ```
+   */
+  trigger?: OutboundWebhookTriggerConfig[];
 }
 
 /**
diff --git a/packages/core/src/start-server.ts b/packages/core/src/start-server.ts
index dc2b422..9999270 100644
--- a/packages/core/src/start-server.ts
+++ b/packages/core/src/start-server.ts
@@ -18,6 +18,7 @@ import {
   WebhookQueue,
   setWebhookHooks,
   processWebhookBatch,
+  OutboundWebhookManager,
 } from '@/webhooks/index.js';
 
 export interface StartServerOptions {
@@ -75,6 +76,18 @@ export async function startServer(options: StartServerOptions = {}) {
     setWebhookHooks(webhookConfig.hooks);
   }
 
+  // Configure outbound webhook triggers if specified
+  const outboundTriggers = webhookConfig.trigger;
+  if (outboundTriggers && outboundTriggers.length > 0) {
+    const outboundManager = new OutboundWebhookManager(outboundTriggers);
+    webhookQueue.on('webhook:batch-complete', (batch) => {
+      void outboundManager.triggerAll(batch);
+    });
+    console.log(
+      `📤 Outbound webhooks configured: ${outboundTriggers.length} endpoint(s)`
+    );
+  }
+
   console.log(
     `🔗 Webhook queue configured (debounce: ${webhookQueue.getDebounceMs()}ms, maxSize: ${webhookQueue.getMaxQueueSize()})`
   );
diff --git a/packages/core/src/webhooks/index.ts b/packages/core/src/webhooks/index.ts
index da8fbc7..4489142 100644
--- a/packages/core/src/webhooks/index.ts
+++ b/packages/core/src/webhooks/index.ts
@@ -58,3 +58,12 @@ export {
   initializeWebhookProcessor,
   processWebhookBatch,
 } from './processor.js';
+
+// Outbound
+export type {
+  OutboundWebhookConfig,
+  OutboundWebhookPayload,
+  OutboundWebhookResult,
+} from './outbound.js';
+
+export { OutboundWebhookManager } from './outbound.js';
diff --git a/packages/core/src/webhooks/outbound.ts b/packages/core/src/webhooks/outbound.ts
new file mode 100644
index 0000000..9637672
--- /dev/null
+++ b/packages/core/src/webhooks/outbound.ts
@@ -0,0 +1,245 @@
+/**
+ * Outbound Webhook Manager
+ *
+ * Triggers outbound webhooks to notify external systems (e.g., Vercel deploy hooks,
+ * CI systems) after webhook batches are processed. Enables the "30 webhooks → 1 build"
+ * optimization.
+ */
+
+import type { WebhookBatch } from './queue.js';
+
+/**
+ * Configuration for an outbound webhook trigger.
+ */
+export interface OutboundWebhookConfig {
+  /** URL to POST to */
+  url: string;
+  /**
+   * Events to trigger on. '*' = all events.
+   * @default ['*']
+   */
+  events?: string[];
+  /** Custom headers to include in the request */
+  headers?: Record<string, string>;
+  /**
+   * Number of retries on failure.
+   * @default 3
+   */
+  retries?: number;
+  /**
+   * Base delay between retries in milliseconds.
+   * Uses exponential backoff: retryDelayMs * (attempt + 1)
+   * @default 1000
+   */
+  retryDelayMs?: number;
+}
+
+/**
+ * Payload sent to outbound webhook endpoints.
+ */
+export interface OutboundWebhookPayload {
+  /** Event type */
+  event: 'batch-complete';
+  /** Timestamp of batch completion (ISO 8601) */
+  timestamp: string;
+  /** Summary of what changed */
+  summary: {
+    /** Number of webhooks in batch */
+    webhookCount: number;
+    /** Plugins that were updated */
+    plugins: string[];
+    /** Node types that were updated (if available) */
+    nodeTypes?: string[];
+  };
+  /** UDL instance identifier (for multi-instance setups) */
+  source: string;
+}
+
+/**
+ * Result of triggering an outbound webhook.
+ */
+export interface OutboundWebhookResult {
+  /** The webhook configuration */
+  config: OutboundWebhookConfig;
+  /** Whether the webhook was successfully sent */
+  success: boolean;
+  /** Error message if failed */
+  error?: string;
+  /** Number of attempts made */
+  attempts: number;
+}
+
+/**
+ * Manages outbound webhook notifications after batch processing.
+ *
+ * @example
+ * ```typescript
+ * const manager = new OutboundWebhookManager([
+ *   {
+ *     url: 'https://api.vercel.com/v1/integrations/deploy/...',
+ *     retries: 3,
+ *   },
+ * ]);
+ *
+ * webhookQueue.on('webhook:batch-complete', (batch) => {
+ *   manager.triggerAll(batch);
+ * });
+ * ```
+ */
+export class OutboundWebhookManager {
+  private configs: OutboundWebhookConfig[];
+
+  constructor(configs: OutboundWebhookConfig[] = []) {
+    this.configs = configs;
+  }
+
+  /**
+   * Trigger all configured outbound webhooks with the batch summary.
+   * All webhooks are triggered in parallel using Promise.allSettled.
+   * Errors are logged but do not throw.
+   *
+   * @param batch - The completed webhook batch
+   * @returns Results for each configured webhook
+   */
+  async triggerAll(batch: WebhookBatch): Promise<OutboundWebhookResult[]> {
+    if (this.configs.length === 0) {
+      return [];
+    }
+
+    const payload = this.createPayload(batch);
+
+    const promises = this.configs.map((config) =>
+      this.trigger(config, payload)
+    );
+
+    const settledResults = await Promise.allSettled(promises);
+
+    const results: OutboundWebhookResult[] = settledResults.map(
+      (result, index) => {
+        const config = this.configs[index]!;
+
+        if (result.status === 'fulfilled') {
+          if (result.value.success) {
+            console.log(`📤 Outbound webhook sent: ${config.url}`);
+          } else {
+            console.error(
+              `❌ Outbound webhook failed: ${config.url} - ${result.value.error}`
+            );
+          }
+          return result.value;
+        } else {
+          // This shouldn't happen since trigger() catches errors, but handle it anyway
+          console.error(
+            `❌ Outbound webhook failed: ${config.url}`,
+            result.reason
+          );
+          return {
+            config,
+            success: false,
+            error:
+              result.reason instanceof Error
+                ? result.reason.message
+                : String(result.reason),
+            attempts: 0,
+          };
+        }
+      }
+    );
+
+    return results;
+  }
+
+  /**
+   * Trigger a single outbound webhook with retry logic.
+   *
+   * @param config - The webhook configuration
+   * @param payload - The payload to send
+   * @returns The result of the trigger attempt
+   */
+  private async trigger(
+    config: OutboundWebhookConfig,
+    payload: OutboundWebhookPayload
+  ): Promise<OutboundWebhookResult> {
+    const { url, headers = {}, retries = 3, retryDelayMs = 1000 } = config;
+
+    let lastError: Error | undefined;
+
+    for (let attempt = 0; attempt <= retries; attempt++) {
+      try {
+        const response = await fetch(url, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            'User-Agent': 'UDL-Webhook/1.0',
+            ...headers,
+          },
+          body: JSON.stringify(payload),
+        });
+
+        if (!response.ok) {
+          throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+        }
+
+        return {
+          config,
+          success: true,
+          attempts: attempt + 1,
+        };
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+
+        if (attempt < retries) {
+          const delay = retryDelayMs * (attempt + 1);
+          console.warn(
+            `⚠️ Outbound webhook retry ${attempt + 1}/${retries}: ${url} (waiting ${delay}ms)`
+          );
+          await this.sleep(delay);
+        }
+      }
+    }
+
+    return {
+      config,
+      success: false,
+      error: lastError?.message ?? 'Unknown error',
+      attempts: retries + 1,
+    };
+  }
+
+  /**
+   * Create the outbound webhook payload from a batch.
+   *
+   * @param batch - The completed webhook batch
+   * @returns The payload to send
+   */
+  private createPayload(batch: WebhookBatch): OutboundWebhookPayload {
+    // Extract unique plugin names from the batch
+    const plugins = [...new Set(batch.webhooks.map((w) => w.pluginName))];
+
+    return {
+      event: 'batch-complete',
+      timestamp: new Date(batch.completedAt).toISOString(),
+      summary: {
+        webhookCount: batch.webhooks.length,
+        plugins,
+      },
+      source: process.env['UDL_INSTANCE_ID'] || 'default',
+    };
+  }
+
+  /**
+   * Sleep for the specified duration.
+   *
+   * @param ms - Milliseconds to sleep
+   */
+  private sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+
+  /**
+   * Get the number of configured outbound webhooks.
+   */
+  getConfigCount(): number {
+    return this.configs.length;
+  }
+}
diff --git a/packages/core/tests/integration/webhook-routing.test.ts b/packages/core/tests/integration/webhook-routing.test.ts
index 9ea236a..b52f440 100644
--- a/packages/core/tests/integration/webhook-routing.test.ts
+++ b/packages/core/tests/integration/webhook-routing.test.ts
@@ -1,4 +1,12 @@
-import { describe, it, expect, beforeAll, afterAll, beforeEach } from 'vitest';
+import {
+  describe,
+  it,
+  expect,
+  beforeAll,
+  afterAll,
+  beforeEach,
+  afterEach,
+} from 'vitest';
 import http, {
   createServer,
   type Server,
@@ -12,8 +20,10 @@ import {
   setDefaultWebhookQueue,
   resetWebhookHooks,
   processWebhookBatch,
+  OutboundWebhookManager,
   type WebhookRegistration,
   type WebhookHandlerContext,
+  type WebhookBatch,
 } from '@/webhooks/index.js';
 import { NodeStore } from '@/nodes/store.js';
 import { setDefaultStore } from '@/nodes/defaultStore.js';
@@ -489,4 +499,244 @@ describe('webhook routing integration', () => {
       expect(calls).toEqual(['plugin-a', 'plugin-b']);
     });
   });
+
+  describe('outbound webhook triggering', () => {
+    let mockOutboundServer: Server;
+    let receivedOutboundPayloads: unknown[];
+    let mockOutboundPort: number;
+    let batchCompleteHandler: ((batch: WebhookBatch) => void) | null = null;
+
+    beforeAll(() => {
+      receivedOutboundPayloads = [];
+      mockOutboundServer = createServer((req, res) => {
+        let body = '';
+        req.on('data', (chunk: Buffer) => {
+          body += chunk.toString();
+        });
+        req.on('end', () => {
+          try {
+            receivedOutboundPayloads.push(JSON.parse(body));
+          } catch {
+            receivedOutboundPayloads.push(body);
+          }
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ received: true }));
+        });
+      });
+
+      return new Promise<void>((resolve) => {
+        mockOutboundServer.listen(0, () => {
+          const address = mockOutboundServer.address();
+          if (address && typeof address !== 'string') {
+            mockOutboundPort = address.port;
+          }
+          resolve();
+        });
+      });
+    });
+
+    afterAll(() => {
+      return new Promise<void>((resolve) => {
+        mockOutboundServer.close(() => resolve());
+      });
+    });
+
+    // Create a separate queue for outbound tests with proper debounce
+    let outboundQueue: WebhookQueue;
+
+    beforeEach(() => {
+      receivedOutboundPayloads = [];
+      batchCompleteHandler = null;
+
+      // Use a small debounce (50ms) to ensure all HTTP requests arrive before processing
+      // This is needed because HTTP requests can arrive out of order
+      outboundQueue = new WebhookQueue({
+        debounceMs: 50,
+        batchProcessor: processWebhookBatch,
+      });
+      setDefaultWebhookQueue(outboundQueue);
+    });
+
+    afterEach(() => {
+      // Remove the batch-complete listener if it was registered
+      if (batchCompleteHandler) {
+        outboundQueue.removeListener(
+          'webhook:batch-complete',
+          batchCompleteHandler
+        );
+        batchCompleteHandler = null;
+      }
+    });
+
+    it('should trigger outbound webhook after batch processing', async () => {
+      // Set up outbound manager listening to queue events
+      const outboundManager = new OutboundWebhookManager([
+        { url: `http://localhost:${mockOutboundPort}/webhook` },
+      ]);
+
+      batchCompleteHandler = (batch: WebhookBatch) => {
+        void outboundManager.triggerAll(batch);
+      };
+      outboundQueue.on('webhook:batch-complete', batchCompleteHandler);
+
+      // Register a simple handler
+      registry.register('test-plugin', {
+        path: 'sync',
+        handler: async (_req, res) => {
+          res.writeHead(200);
+          res.end('OK');
+        },
+      });
+
+      // Clear payloads right before sending webhooks (in case of delayed arrivals from previous tests)
+      receivedOutboundPayloads = [];
+
+      // Send multiple webhooks
+      await makeRequest(server, '/_webhooks/test-plugin/sync', {
+        body: JSON.stringify({ id: 1 }),
+      });
+      await makeRequest(server, '/_webhooks/test-plugin/sync', {
+        body: JSON.stringify({ id: 2 }),
+      });
+      await makeRequest(server, '/_webhooks/test-plugin/sync', {
+        body: JSON.stringify({ id: 3 }),
+      });
+
+      // Flush queue to process the batch
+      await outboundQueue.flush();
+
+      // Wait for outbound webhook to complete
+      await new Promise((resolve) => setTimeout(resolve, 100));
+
+      // Verify outbound webhook was triggered once
+      expect(receivedOutboundPayloads.length).toBe(1);
+
+      const payload = receivedOutboundPayloads[0] as {
+        event: string;
+        summary: { webhookCount: number; plugins: string[] };
+      };
+      expect(payload.event).toBe('batch-complete');
+      expect(payload.summary.webhookCount).toBe(3);
+      expect(payload.summary.plugins).toContain('test-plugin');
+    });
+
+    it('should include correct batch summary in outbound payload', async () => {
+      const outboundManager = new OutboundWebhookManager([
+        { url: `http://localhost:${mockOutboundPort}/webhook` },
+      ]);
+
+      batchCompleteHandler = (batch: WebhookBatch) => {
+        void outboundManager.triggerAll(batch);
+      };
+      outboundQueue.on('webhook:batch-complete', batchCompleteHandler);
+
+      // Register handlers for multiple plugins
+      registry.register('plugin-a', {
+        path: 'update',
+        handler: async (_req, res) => {
+          res.writeHead(200);
+          res.end('OK');
+        },
+      });
+
+      registry.register('plugin-b', {
+        path: 'sync',
+        handler: async (_req, res) => {
+          res.writeHead(200);
+          res.end('OK');
+        },
+      });
+
+      // Clear payloads right before sending webhooks (in case of delayed arrivals from previous tests)
+      receivedOutboundPayloads = [];
+
+      // Send webhooks to different plugins
+      await makeRequest(server, '/_webhooks/plugin-a/update', { body: '{}' });
+      await makeRequest(server, '/_webhooks/plugin-b/sync', { body: '{}' });
+      await makeRequest(server, '/_webhooks/plugin-a/update', { body: '{}' });
+
+      await outboundQueue.flush();
+      await new Promise((resolve) => setTimeout(resolve, 100));
+
+      expect(receivedOutboundPayloads.length).toBe(1);
+
+      const payload = receivedOutboundPayloads[0] as {
+        event: string;
+        timestamp: string;
+        summary: { webhookCount: number; plugins: string[] };
+        source: string;
+      };
+
+      expect(payload.event).toBe('batch-complete');
+      expect(payload.timestamp).toBeDefined();
+      expect(payload.summary.webhookCount).toBe(3);
+      expect(payload.summary.plugins).toContain('plugin-a');
+      expect(payload.summary.plugins).toContain('plugin-b');
+      expect(payload.source).toBeDefined();
+    });
+
+    it('should trigger multiple outbound webhooks in parallel', async () => {
+      // Create a second mock server
+      let secondServerPayloads: unknown[] = [];
+      const secondMockServer = createServer((req, res) => {
+        let body = '';
+        req.on('data', (chunk: Buffer) => {
+          body += chunk.toString();
+        });
+        req.on('end', () => {
+          try {
+            secondServerPayloads.push(JSON.parse(body));
+          } catch {
+            secondServerPayloads.push(body);
+          }
+          res.writeHead(200);
+          res.end('OK');
+        });
+      });
+
+      const secondPort = await new Promise<number>((resolve) => {
+        secondMockServer.listen(0, () => {
+          const address = secondMockServer.address();
+          if (address && typeof address !== 'string') {
+            resolve(address.port);
+          }
+        });
+      });
+
+      try {
+        const outboundManager = new OutboundWebhookManager([
+          { url: `http://localhost:${mockOutboundPort}/webhook` },
+          { url: `http://localhost:${secondPort}/webhook` },
+        ]);
+
+        batchCompleteHandler = (batch: WebhookBatch) => {
+          void outboundManager.triggerAll(batch);
+        };
+        outboundQueue.on('webhook:batch-complete', batchCompleteHandler);
+
+        registry.register('plugin', {
+          path: 'test',
+          handler: async (_req, res) => {
+            res.writeHead(200);
+            res.end('OK');
+          },
+        });
+
+        // Clear payloads right before sending webhooks (in case of delayed arrivals from previous tests)
+        receivedOutboundPayloads = [];
+
+        await makeRequest(server, '/_webhooks/plugin/test', { body: '{}' });
+        await outboundQueue.flush();
+        await new Promise((resolve) => setTimeout(resolve, 100));
+
+        // Both endpoints should receive the payload
+        expect(receivedOutboundPayloads.length).toBe(1);
+        expect(secondServerPayloads.length).toBe(1);
+      } finally {
+        await new Promise<void>((resolve) => {
+          secondMockServer.close(() => resolve());
+        });
+      }
+    });
+  });
 });
diff --git a/packages/core/tests/unit/webhooks/outbound.test.ts b/packages/core/tests/unit/webhooks/outbound.test.ts
new file mode 100644
index 0000000..c014bf8
--- /dev/null
+++ b/packages/core/tests/unit/webhooks/outbound.test.ts
@@ -0,0 +1,465 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import {
+  OutboundWebhookManager,
+  type OutboundWebhookConfig,
+  type WebhookBatch,
+  type QueuedWebhook,
+} from '@/webhooks/index.js';
+
+// Helper to create a mock webhook batch
+function createMockBatch(
+  webhookCount: number,
+  plugins: string[] = ['test-plugin']
+): WebhookBatch {
+  const webhooks: QueuedWebhook[] = [];
+  for (let i = 0; i < webhookCount; i++) {
+    webhooks.push({
+      pluginName: plugins[i % plugins.length]!,
+      path: `path-${i}`,
+      rawBody: Buffer.from('{}'),
+      body: {},
+      headers: { 'content-type': 'application/json' },
+      timestamp: Date.now(),
+    });
+  }
+
+  return {
+    webhooks,
+    startedAt: Date.now() - 100,
+    completedAt: Date.now(),
+  };
+}
+
+describe('OutboundWebhookManager', () => {
+  let fetchMock: ReturnType<typeof vi.fn>;
+  let originalFetch: typeof globalThis.fetch;
+
+  beforeEach(() => {
+    // Mock fetch
+    fetchMock = vi.fn();
+    originalFetch = globalThis.fetch;
+    globalThis.fetch = fetchMock;
+
+    // Suppress console output
+    vi.spyOn(console, 'log').mockImplementation(() => {});
+    vi.spyOn(console, 'warn').mockImplementation(() => {});
+    vi.spyOn(console, 'error').mockImplementation(() => {});
+
+    // Use fake timers for retry delay testing
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    vi.restoreAllMocks();
+    vi.useRealTimers();
+  });
+
+  describe('constructor', () => {
+    it('should create manager with empty config array', () => {
+      const manager = new OutboundWebhookManager([]);
+      expect(manager.getConfigCount()).toBe(0);
+    });
+
+    it('should create manager with provided configs', () => {
+      const configs: OutboundWebhookConfig[] = [
+        { url: 'https://example.com/webhook1' },
+        { url: 'https://example.com/webhook2' },
+      ];
+      const manager = new OutboundWebhookManager(configs);
+      expect(manager.getConfigCount()).toBe(2);
+    });
+
+    it('should default to empty array if no configs provided', () => {
+      const manager = new OutboundWebhookManager();
+      expect(manager.getConfigCount()).toBe(0);
+    });
+  });
+
+  describe('triggerAll', () => {
+    it('should return empty array if no configs', async () => {
+      const manager = new OutboundWebhookManager([]);
+      const batch = createMockBatch(3);
+
+      const results = await manager.triggerAll(batch);
+
+      expect(results).toEqual([]);
+      expect(fetchMock).not.toHaveBeenCalled();
+    });
+
+    it('should trigger single webhook successfully', async () => {
+      fetchMock.mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        statusText: 'OK',
+      });
+
+      const manager = new OutboundWebhookManager([
+        { url: 'https://example.com/webhook' },
+      ]);
+      const batch = createMockBatch(3);
+
+      const results = await manager.triggerAll(batch);
+
+      expect(results.length).toBe(1);
+      expect(results[0]!.success).toBe(true);
+      expect(results[0]!.attempts).toBe(1);
+      expect(fetchMock).toHaveBeenCalledTimes(1);
+    });
+
+    it('should trigger multiple webhooks in parallel', async () => {
+      fetchMock.mockResolvedValue({
+        ok: true,
+        status: 200,
+        statusText: 'OK',
+      });
+
+      const manager = new OutboundWebhookManager([
+        { url: 'https://example.com/webhook1' },
+        { url: 'https://example.com/webhook2' },
+        { url: 'https://example.com/webhook3' },
+      ]);
+      const batch = createMockBatch(5);
+
+      const results = await manager.triggerAll(batch);
+
+      expect(results.length).toBe(3);
+      expect(results.every((r) => r.success)).toBe(true);
+      expect(fetchMock).toHaveBeenCalledTimes(3);
+    });
+
+    it('should send correct payload structure', async () => {
+      fetchMock.mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        statusText: 'OK',
+      });
+
+      const manager = new OutboundWebhookManager([
+        { url: 'https://example.com/webhook' },
+      ]);
+      const batch = createMockBatch(3, ['plugin-a', 'plugin-b']);
+
+      await manager.triggerAll(batch);
+
+      expect(fetchMock).toHaveBeenCalledWith(
+        'https://example.com/webhook',
+        expect.objectContaining({
+          method: 'POST',
+          headers: expect.objectContaining({
+            'Content-Type': 'application/json',
+            'User-Agent': 'UDL-Webhook/1.0',
+          }),
+        })
+      );
+
+      const callArgs = fetchMock.mock.calls[0]!;
+      const body = JSON.parse((callArgs[1] as { body: string }).body);
+
+      expect(body.event).toBe('batch-complete');
+      expect(body.timestamp).toBeDefined();
+      expect(body.summary.webhookCount).toBe(3);
+      expect(body.summary.plugins).toContain('plugin-a');
+      expect(body.summary.plugins).toContain('plugin-b');
+      expect(body.source).toBeDefined();
+    });
+
+    it('should include custom headers in request', async () => {
+      fetchMock.mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        statusText: 'OK',
+      });
+
+      const manager = new OutboundWebhookManager([
+        {
+          url: 'https://example.com/webhook',
+          headers: {
+            Authorization: 'Bearer secret-token',
+            'X-Custom-Header': 'custom-value',
+          },
+        },
+      ]);
+      const batch = createMockBatch(1);
+
+      await manager.triggerAll(batch);
+
+      expect(fetchMock).toHaveBeenCalledWith(
+        'https://example.com/webhook',
+        expect.objectContaining({
+          headers: expect.objectContaining({
+            Authorization: 'Bearer secret-token',
+            'X-Custom-Header': 'custom-value',
+          }),
+        })
+      );
+    });
+
+    it('should handle failed webhooks without throwing', async () => {
+      fetchMock
+        .mockResolvedValueOnce({ ok: true, status: 200, statusText: 'OK' })
+        .mockRejectedValueOnce(new Error('Network error'))
+        .mockResolvedValueOnce({ ok: true, status: 200, statusText: 'OK' });
+
+      const manager = new OutboundWebhookManager([
+        { url: 'https://example.com/webhook1', retries: 0 },
+        { url: 'https://example.com/webhook2', retries: 0 },
+        { url: 'https://example.com/webhook3', retries: 0 },
+      ]);
+      const batch = createMockBatch(1);
+
+      const results = await manager.triggerAll(batch);
+
+      expect(results.length).toBe(3);
+      expect(results[0]!.success).toBe(true);
+      expect(results[1]!.success).toBe(false);
+      expect(results[1]!.error).toBe('Network error');
+      expect(results[2]!.success).toBe(true);
+    });
+
+    it('should handle HTTP error responses', async () => {
+      fetchMock.mockResolvedValueOnce({
+        ok: false,
+        status: 500,
+        statusText: 'Internal Server Error',
+      });
+
+      const manager = new OutboundWebhookManager([
+        { url: 'https://example.com/webhook', retries: 0 },
+      ]);
+      const batch = createMockBatch(1);
+
+      const results = await manager.triggerAll(batch);
+
+      expect(results[0]!.success).toBe(false);
+      expect(results[0]!.error).toBe('HTTP 500: Internal Server Error');
+    });
+
+    it('should extract unique plugins from batch', async () => {
+      fetchMock.mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        statusText: 'OK',
+      });
+
+      const manager = new OutboundWebhookManager([
+        { url: 'https://example.com/webhook' },
+      ]);
+
+      // Create batch with duplicate plugin names
+      const batch: WebhookBatch = {
+        webhooks: [
+          {
+            pluginName: 'plugin-a',
+            path: 'path-1',
+            rawBody: Buffer.from('{}'),
+            body: {},
+            headers: {},
+            timestamp: Date.now(),
+          },
+          {
+            pluginName: 'plugin-a',
+            path: 'path-2',
+            rawBody: Buffer.from('{}'),
+            body: {},
+            headers: {},
+            timestamp: Date.now(),
+          },
+          {
+            pluginName: 'plugin-b',
+            path: 'path-3',
+            rawBody: Buffer.from('{}'),
+            body: {},
+            headers: {},
+            timestamp: Date.now(),
+          },
+        ],
+        startedAt: Date.now() - 100,
+        completedAt: Date.now(),
+      };
+
+      await manager.triggerAll(batch);
+
+      const callArgs = fetchMock.mock.calls[0]!;
+      const body = JSON.parse((callArgs[1] as { body: string }).body);
+
+      // Should have unique plugins only
+      expect(body.summary.plugins).toEqual(['plugin-a', 'plugin-b']);
+    });
+  });
+
+  describe('retry logic', () => {
+    it('should retry on failure', async () => {
+      fetchMock
+        .mockRejectedValueOnce(new Error('Temporary error'))
+        .mockRejectedValueOnce(new Error('Temporary error'))
+        .mockResolvedValueOnce({ ok: true, status: 200, statusText: 'OK' });
+
+      const manager = new OutboundWebhookManager([
+        { url: 'https://example.com/webhook', retries: 3, retryDelayMs: 100 },
+      ]);
+      const batch = createMockBatch(1);
+
+      const resultPromise = manager.triggerAll(batch);
+
+      // Advance timers to handle retry delays
+      await vi.advanceTimersByTimeAsync(100); // First retry delay
+      await vi.advanceTimersByTimeAsync(200); // Second retry delay
+
+      const results = await resultPromise;
+
+      expect(results[0]!.success).toBe(true);
+      expect(results[0]!.attempts).toBe(3);
+      expect(fetchMock).toHaveBeenCalledTimes(3);
+    });
+
+    it('should use exponential backoff for retries', async () => {
+      fetchMock
+        .mockRejectedValueOnce(new Error('Error'))
+        .mockRejectedValueOnce(new Error('Error'))
+        .mockRejectedValueOnce(new Error('Error'))
+        .mockResolvedValueOnce({ ok: true, status: 200, statusText: 'OK' });
+
+      const manager = new OutboundWebhookManager([
+        { url: 'https://example.com/webhook', retries: 3, retryDelayMs: 1000 },
+      ]);
+      const batch = createMockBatch(1);
+
+      const resultPromise = manager.triggerAll(batch);
+
+      // First retry: 1000ms * 1 = 1000ms
+      expect(fetchMock).toHaveBeenCalledTimes(1);
+      await vi.advanceTimersByTimeAsync(1000);
+      expect(fetchMock).toHaveBeenCalledTimes(2);
+
+      // Second retry: 1000ms * 2 = 2000ms
+      await vi.advanceTimersByTimeAsync(2000);
+      expect(fetchMock).toHaveBeenCalledTimes(3);
+
+      // Third retry: 1000ms * 3 = 3000ms
+      await vi.advanceTimersByTimeAsync(3000);
+      expect(fetchMock).toHaveBeenCalledTimes(4);
+
+      const results = await resultPromise;
+      expect(results[0]!.success).toBe(true);
+    });
+
+    it('should give up after max retries', async () => {
+      fetchMock.mockRejectedValue(new Error('Persistent error'));
+
+      const manager = new OutboundWebhookManager([
+        { url: 'https://example.com/webhook', retries: 2, retryDelayMs: 100 },
+      ]);
+      const batch = createMockBatch(1);
+
+      const resultPromise = manager.triggerAll(batch);
+
+      // Advance through all retries
+      await vi.advanceTimersByTimeAsync(100); // First retry
+      await vi.advanceTimersByTimeAsync(200); // Second retry
+
+      const results = await resultPromise;
+
+      expect(results[0]!.success).toBe(false);
+      expect(results[0]!.error).toBe('Persistent error');
+      expect(results[0]!.attempts).toBe(3); // Initial + 2 retries
+      expect(fetchMock).toHaveBeenCalledTimes(3);
+    });
+
+    it('should use default retry settings', async () => {
+      fetchMock.mockRejectedValue(new Error('Error'));
+
+      const manager = new OutboundWebhookManager([
+        { url: 'https://example.com/webhook' }, // No retry config, uses defaults
+      ]);
+      const batch = createMockBatch(1);
+
+      const resultPromise = manager.triggerAll(batch);
+
+      // Default is 3 retries, so 4 total attempts
+      await vi.advanceTimersByTimeAsync(1000); // retry 1
+      await vi.advanceTimersByTimeAsync(2000); // retry 2
+      await vi.advanceTimersByTimeAsync(3000); // retry 3
+
+      await resultPromise;
+
+      expect(fetchMock).toHaveBeenCalledTimes(4);
+    });
+  });
+
+  describe('UDL_INSTANCE_ID', () => {
+    it('should use UDL_INSTANCE_ID from environment if set', async () => {
+      const originalEnv = process.env['UDL_INSTANCE_ID'];
+      process.env['UDL_INSTANCE_ID'] = 'my-custom-instance';
+
+      fetchMock.mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        statusText: 'OK',
+      });
+
+      const manager = new OutboundWebhookManager([
+        { url: 'https://example.com/webhook' },
+      ]);
+      const batch = createMockBatch(1);
+
+      await manager.triggerAll(batch);
+
+      const callArgs = fetchMock.mock.calls[0]!;
+      const body = JSON.parse((callArgs[1] as { body: string }).body);
+
+      expect(body.source).toBe('my-custom-instance');
+
+      // Restore
+      if (originalEnv === undefined) {
+        delete process.env['UDL_INSTANCE_ID'];
+      } else {
+        process.env['UDL_INSTANCE_ID'] = originalEnv;
+      }
+    });
+
+    it('should use "default" if UDL_INSTANCE_ID is not set', async () => {
+      const originalEnv = process.env['UDL_INSTANCE_ID'];
+      delete process.env['UDL_INSTANCE_ID'];
+
+      fetchMock.mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        statusText: 'OK',
+      });
+
+      const manager = new OutboundWebhookManager([
+        { url: 'https://example.com/webhook' },
+      ]);
+      const batch = createMockBatch(1);
+
+      await manager.triggerAll(batch);
+
+      const callArgs = fetchMock.mock.calls[0]!;
+      const body = JSON.parse((callArgs[1] as { body: string }).body);
+
+      expect(body.source).toBe('default');
+
+      // Restore
+      if (originalEnv !== undefined) {
+        process.env['UDL_INSTANCE_ID'] = originalEnv;
+      }
+    });
+  });
+
+  describe('getConfigCount', () => {
+    it('should return 0 for empty manager', () => {
+      const manager = new OutboundWebhookManager([]);
+      expect(manager.getConfigCount()).toBe(0);
+    });
+
+    it('should return correct count', () => {
+      const manager = new OutboundWebhookManager([
+        { url: 'https://example.com/1' },
+        { url: 'https://example.com/2' },
+        { url: 'https://example.com/3' },
+      ]);
+      expect(manager.getConfigCount()).toBe(3);
+    });
+  });
+});

From 87b62316fcf18f3559e0dcddb3ebe08ebc4bb9e2 Mon Sep 17 00:00:00 2001
From: dawidurbanski <hi@dawidurbanski.com>
Date: Mon, 22 Dec 2025 11:48:58 +0100
Subject: [PATCH 08/46] feat(core): add deletion log for partial sync support

---
 .changeset/deletion-log.md                    |  36 ++
 packages/core/src/sync/deletion-log.ts        | 152 +++++++
 .../core/tests/unit/sync/deletion-log.test.ts | 412 ++++++++++++++++++
 3 files changed, 600 insertions(+)
 create mode 100644 .changeset/deletion-log.md
 create mode 100644 packages/core/src/sync/deletion-log.ts
 create mode 100644 packages/core/tests/unit/sync/deletion-log.test.ts

diff --git a/.changeset/deletion-log.md b/.changeset/deletion-log.md
new file mode 100644
index 0000000..11824ed
--- /dev/null
+++ b/.changeset/deletion-log.md
@@ -0,0 +1,36 @@
+---
+'universal-data-layer': minor
+---
+
+Add deletion log for partial sync support
+
+This release introduces a DeletionLog class that tracks node deletions with timestamps, enabling clients to perform partial sync without needing a full refetch.
+
+**Features:**
+
+- `DeletionLog` class for tracking deleted nodes
+- `recordDeletion(node)`: Record a node deletion with timestamp
+- `getDeletedSince(timestamp)`: Query deletions after a given time
+- `cleanup()`: Remove entries older than TTL (default: 30 days)
+- Serialization support via `toJSON()` and `fromJSON()` for persistence
+- Configurable TTL (time-to-live) for deletion entries
+
+**Example usage:**
+
+```typescript
+import { DeletionLog } from 'universal-data-layer';
+
+const log = new DeletionLog(30); // 30 day TTL
+
+// Record a deletion
+log.recordDeletion(deletedNode);
+
+// Query deletions since last sync
+const deletedSince = log.getDeletedSince(lastSyncTimestamp);
+
+// Serialize for persistence
+const data = log.toJSON();
+
+// Restore from persistence
+const restored = DeletionLog.fromJSON(data);
+```
diff --git a/packages/core/src/sync/deletion-log.ts b/packages/core/src/sync/deletion-log.ts
new file mode 100644
index 0000000..17a1432
--- /dev/null
+++ b/packages/core/src/sync/deletion-log.ts
@@ -0,0 +1,152 @@
+/**
+ * Entry in the deletion log tracking a deleted node
+ */
+export interface DeletionLogEntry {
+  /** Node ID that was deleted */
+  nodeId: string;
+  /** Node type (for filtering) */
+  nodeType: string;
+  /** Plugin that owned the node */
+  owner: string;
+  /** ISO 8601 timestamp of deletion */
+  deletedAt: string;
+}
+
+/**
+ * Serializable deletion log data structure
+ */
+export interface DeletionLogData {
+  /** Deletion entries */
+  entries: DeletionLogEntry[];
+  /** Last cleanup timestamp (ISO 8601) */
+  lastCleanup: string;
+}
+
+/** Default TTL in days */
+const DEFAULT_TTL_DAYS = 30;
+
+/**
+ * Minimal node information required for recording a deletion
+ */
+export interface DeletionNodeInfo {
+  internal: {
+    id: string;
+    type: string;
+    owner: string;
+  };
+}
+
+/**
+ * Tracks node deletions with timestamps for partial sync support.
+ *
+ * The deletion log enables clients to perform partial sync by querying
+ * "what was deleted since timestamp X?" and removing those nodes from
+ * their local cache.
+ *
+ * Entries are automatically cleaned up after the TTL expires (default: 30 days).
+ *
+ * @example
+ * ```ts
+ * const log = new DeletionLog();
+ *
+ * // Record a deletion
+ * log.recordDeletion(node);
+ *
+ * // Query deletions since a timestamp
+ * const deleted = log.getDeletedSince('2024-01-01T00:00:00.000Z');
+ *
+ * // Serialize for persistence
+ * const data = log.toJSON();
+ *
+ * // Restore from persistence
+ * const restored = DeletionLog.fromJSON(data);
+ * ```
+ */
+export class DeletionLog {
+  private entries: DeletionLogEntry[] = [];
+  private readonly ttlMs: number;
+
+  /**
+   * Create a new deletion log.
+   * @param ttlDays - Time-to-live for entries in days (default: 30)
+   */
+  constructor(ttlDays: number = DEFAULT_TTL_DAYS) {
+    this.ttlMs = ttlDays * 24 * 60 * 60 * 1000;
+  }
+
+  /**
+   * Record a node deletion.
+   * @param node - The node that was deleted (must have internal.id, internal.type, internal.owner)
+   */
+  recordDeletion(node: DeletionNodeInfo): void {
+    const entry: DeletionLogEntry = {
+      nodeId: node.internal.id,
+      nodeType: node.internal.type,
+      owner: node.internal.owner,
+      deletedAt: new Date().toISOString(),
+    };
+
+    this.entries.push(entry);
+  }
+
+  /**
+   * Get all deletions since a given timestamp.
+   * @param since - ISO 8601 timestamp string or Date object
+   * @returns Array of deletion entries after the given timestamp
+   */
+  getDeletedSince(since: string | Date): DeletionLogEntry[] {
+    const sinceMs = new Date(since).getTime();
+    return this.entries.filter(
+      (entry) => new Date(entry.deletedAt).getTime() > sinceMs
+    );
+  }
+
+  /**
+   * Clean up entries older than TTL.
+   * @returns Number of entries removed
+   */
+  cleanup(): number {
+    const cutoff = Date.now() - this.ttlMs;
+    const before = this.entries.length;
+
+    this.entries = this.entries.filter(
+      (entry) => new Date(entry.deletedAt).getTime() > cutoff
+    );
+
+    return before - this.entries.length;
+  }
+
+  /**
+   * Serialize the deletion log for persistence.
+   * @returns Serializable deletion log data
+   */
+  toJSON(): DeletionLogData {
+    return {
+      entries: [...this.entries],
+      lastCleanup: new Date().toISOString(),
+    };
+  }
+
+  /**
+   * Restore a deletion log from persisted data.
+   * Runs cleanup on load to remove expired entries.
+   *
+   * @param data - Persisted deletion log data
+   * @param ttlDays - Optional TTL override (default: 30)
+   * @returns Restored DeletionLog instance
+   */
+  static fromJSON(data: DeletionLogData, ttlDays?: number): DeletionLog {
+    const log = new DeletionLog(ttlDays);
+    log.entries = data.entries.map((entry) => ({ ...entry }));
+    log.cleanup();
+    return log;
+  }
+
+  /**
+   * Get the current number of entries.
+   * @returns Entry count
+   */
+  size(): number {
+    return this.entries.length;
+  }
+}
diff --git a/packages/core/tests/unit/sync/deletion-log.test.ts b/packages/core/tests/unit/sync/deletion-log.test.ts
new file mode 100644
index 0000000..87883a3
--- /dev/null
+++ b/packages/core/tests/unit/sync/deletion-log.test.ts
@@ -0,0 +1,412 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import {
+  DeletionLog,
+  type DeletionLogData,
+  type DeletionNodeInfo,
+} from '@/sync/deletion-log.js';
+
+/** Helper to create a mock node for testing */
+function createMockNode(
+  overrides: Partial<DeletionNodeInfo['internal']> = {}
+): DeletionNodeInfo {
+  return {
+    internal: {
+      id: 'node-1',
+      type: 'TestNode',
+      owner: 'test-plugin',
+      ...overrides,
+    },
+  };
+}
+
+describe('DeletionLog', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date('2024-06-15T12:00:00.000Z'));
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  describe('constructor', () => {
+    it('creates an empty deletion log', () => {
+      const log = new DeletionLog();
+      expect(log.size()).toBe(0);
+    });
+
+    it('accepts custom TTL in days', () => {
+      const log = new DeletionLog(7);
+      expect(log.size()).toBe(0);
+    });
+  });
+
+  describe('recordDeletion', () => {
+    it('adds entry with correct fields', () => {
+      const log = new DeletionLog();
+      const node = createMockNode({
+        id: 'product-123',
+        type: 'Product',
+        owner: 'shopify-plugin',
+      });
+
+      log.recordDeletion(node);
+
+      expect(log.size()).toBe(1);
+      const entries = log.getDeletedSince(new Date(0));
+      expect(entries).toHaveLength(1);
+      expect(entries[0]).toEqual({
+        nodeId: 'product-123',
+        nodeType: 'Product',
+        owner: 'shopify-plugin',
+        deletedAt: '2024-06-15T12:00:00.000Z',
+      });
+    });
+
+    it('adds entry with current timestamp', () => {
+      const log = new DeletionLog();
+
+      log.recordDeletion(createMockNode());
+
+      const entries = log.getDeletedSince(new Date(0));
+      expect(entries[0].deletedAt).toBe('2024-06-15T12:00:00.000Z');
+    });
+
+    it('records multiple deletions', () => {
+      const log = new DeletionLog();
+
+      log.recordDeletion(createMockNode({ id: 'node-1' }));
+      vi.advanceTimersByTime(1000);
+      log.recordDeletion(createMockNode({ id: 'node-2' }));
+      vi.advanceTimersByTime(1000);
+      log.recordDeletion(createMockNode({ id: 'node-3' }));
+
+      expect(log.size()).toBe(3);
+    });
+  });
+
+  describe('getDeletedSince', () => {
+    it('returns entries deleted after the given timestamp', () => {
+      const log = new DeletionLog();
+
+      // Record at 12:00
+      log.recordDeletion(createMockNode({ id: 'node-1' }));
+
+      // Advance 1 hour and record
+      vi.advanceTimersByTime(60 * 60 * 1000);
+      log.recordDeletion(createMockNode({ id: 'node-2' }));
+
+      // Query for entries after 12:30
+      const entries = log.getDeletedSince('2024-06-15T12:30:00.000Z');
+      expect(entries).toHaveLength(1);
+      expect(entries[0].nodeId).toBe('node-2');
+    });
+
+    it('returns empty array when no matches', () => {
+      const log = new DeletionLog();
+
+      log.recordDeletion(createMockNode());
+
+      const entries = log.getDeletedSince('2024-06-15T13:00:00.000Z');
+      expect(entries).toHaveLength(0);
+    });
+
+    it('returns empty array when log is empty', () => {
+      const log = new DeletionLog();
+
+      const entries = log.getDeletedSince(new Date(0));
+      expect(entries).toHaveLength(0);
+    });
+
+    it('works with Date objects', () => {
+      const log = new DeletionLog();
+
+      log.recordDeletion(createMockNode({ id: 'node-1' }));
+
+      const entries = log.getDeletedSince(new Date('2024-06-15T11:00:00.000Z'));
+      expect(entries).toHaveLength(1);
+    });
+
+    it('works with ISO string timestamps', () => {
+      const log = new DeletionLog();
+
+      log.recordDeletion(createMockNode({ id: 'node-1' }));
+
+      const entries = log.getDeletedSince('2024-06-15T11:00:00.000Z');
+      expect(entries).toHaveLength(1);
+    });
+
+    it('excludes entries at exactly the given timestamp', () => {
+      const log = new DeletionLog();
+
+      log.recordDeletion(createMockNode());
+
+      const entries = log.getDeletedSince('2024-06-15T12:00:00.000Z');
+      expect(entries).toHaveLength(0);
+    });
+  });
+
+  describe('cleanup', () => {
+    it('removes entries older than TTL', () => {
+      const log = new DeletionLog(30); // 30 day TTL
+
+      // Record at current time
+      log.recordDeletion(createMockNode({ id: 'node-1' }));
+
+      // Advance 31 days
+      vi.advanceTimersByTime(31 * 24 * 60 * 60 * 1000);
+
+      const removed = log.cleanup();
+
+      expect(removed).toBe(1);
+      expect(log.size()).toBe(0);
+    });
+
+    it('keeps entries within TTL', () => {
+      const log = new DeletionLog(30);
+
+      log.recordDeletion(createMockNode({ id: 'node-1' }));
+
+      // Advance 29 days
+      vi.advanceTimersByTime(29 * 24 * 60 * 60 * 1000);
+
+      const removed = log.cleanup();
+
+      expect(removed).toBe(0);
+      expect(log.size()).toBe(1);
+    });
+
+    it('returns correct count of removed entries', () => {
+      const log = new DeletionLog(1); // 1 day TTL
+
+      // Record 3 nodes
+      log.recordDeletion(createMockNode({ id: 'node-1' }));
+      log.recordDeletion(createMockNode({ id: 'node-2' }));
+      log.recordDeletion(createMockNode({ id: 'node-3' }));
+
+      // Advance 2 days
+      vi.advanceTimersByTime(2 * 24 * 60 * 60 * 1000);
+
+      const removed = log.cleanup();
+
+      expect(removed).toBe(3);
+    });
+
+    it('only removes entries older than TTL', () => {
+      const log = new DeletionLog(1); // 1 day TTL
+
+      // Record old node
+      log.recordDeletion(createMockNode({ id: 'old-node' }));
+
+      // Advance 2 days
+      vi.advanceTimersByTime(2 * 24 * 60 * 60 * 1000);
+
+      // Record new node
+      log.recordDeletion(createMockNode({ id: 'new-node' }));
+
+      const removed = log.cleanup();
+
+      expect(removed).toBe(1);
+      expect(log.size()).toBe(1);
+      const entries = log.getDeletedSince(new Date(0));
+      expect(entries[0].nodeId).toBe('new-node');
+    });
+
+    it('works with custom TTL', () => {
+      const log = new DeletionLog(7); // 7 day TTL
+
+      log.recordDeletion(createMockNode());
+
+      // Advance 8 days
+      vi.advanceTimersByTime(8 * 24 * 60 * 60 * 1000);
+
+      const removed = log.cleanup();
+      expect(removed).toBe(1);
+    });
+  });
+
+  describe('toJSON', () => {
+    it('returns serializable data structure', () => {
+      const log = new DeletionLog();
+
+      log.recordDeletion(createMockNode({ id: 'node-1' }));
+
+      const data = log.toJSON();
+
+      expect(data).toEqual({
+        entries: [
+          {
+            nodeId: 'node-1',
+            nodeType: 'TestNode',
+            owner: 'test-plugin',
+            deletedAt: '2024-06-15T12:00:00.000Z',
+          },
+        ],
+        lastCleanup: '2024-06-15T12:00:00.000Z',
+      });
+    });
+
+    it('returns copy of entries (not reference)', () => {
+      const log = new DeletionLog();
+
+      log.recordDeletion(createMockNode());
+
+      const data1 = log.toJSON();
+      const data2 = log.toJSON();
+
+      expect(data1.entries).not.toBe(data2.entries);
+    });
+  });
+
+  describe('fromJSON', () => {
+    it('restores deletion log from persisted data', () => {
+      const data: DeletionLogData = {
+        entries: [
+          {
+            nodeId: 'node-1',
+            nodeType: 'Product',
+            owner: 'shopify',
+            deletedAt: '2024-06-15T11:00:00.000Z',
+          },
+        ],
+        lastCleanup: '2024-06-15T11:00:00.000Z',
+      };
+
+      const log = DeletionLog.fromJSON(data);
+
+      expect(log.size()).toBe(1);
+      const entries = log.getDeletedSince(new Date(0));
+      expect(entries[0].nodeId).toBe('node-1');
+    });
+
+    it('runs cleanup on load', () => {
+      const data: DeletionLogData = {
+        entries: [
+          {
+            nodeId: 'old-node',
+            nodeType: 'TestNode',
+            owner: 'test-plugin',
+            deletedAt: '2024-05-01T00:00:00.000Z', // 45 days old
+          },
+          {
+            nodeId: 'new-node',
+            nodeType: 'TestNode',
+            owner: 'test-plugin',
+            deletedAt: '2024-06-15T11:00:00.000Z', // 1 hour old
+          },
+        ],
+        lastCleanup: '2024-05-01T00:00:00.000Z',
+      };
+
+      const log = DeletionLog.fromJSON(data);
+
+      // Old entry should be cleaned up
+      expect(log.size()).toBe(1);
+      const entries = log.getDeletedSince(new Date(0));
+      expect(entries[0].nodeId).toBe('new-node');
+    });
+
+    it('accepts custom TTL override', () => {
+      const data: DeletionLogData = {
+        entries: [
+          {
+            nodeId: 'node-1',
+            nodeType: 'TestNode',
+            owner: 'test-plugin',
+            deletedAt: '2024-06-10T00:00:00.000Z', // 5 days old
+          },
+        ],
+        lastCleanup: '2024-06-10T00:00:00.000Z',
+      };
+
+      // With 3 day TTL, entry should be cleaned up
+      const log = DeletionLog.fromJSON(data, 3);
+      expect(log.size()).toBe(0);
+    });
+
+    it('creates copy of entries (not reference)', () => {
+      const data: DeletionLogData = {
+        entries: [
+          {
+            nodeId: 'node-1',
+            nodeType: 'TestNode',
+            owner: 'test-plugin',
+            deletedAt: '2024-06-15T11:00:00.000Z',
+          },
+        ],
+        lastCleanup: '2024-06-15T11:00:00.000Z',
+      };
+
+      const log = DeletionLog.fromJSON(data);
+
+      // Mutating original should not affect log
+      data.entries[0].nodeId = 'mutated';
+
+      const entries = log.getDeletedSince(new Date(0));
+      expect(entries[0].nodeId).toBe('node-1');
+    });
+  });
+
+  describe('size', () => {
+    it('returns 0 for empty log', () => {
+      const log = new DeletionLog();
+      expect(log.size()).toBe(0);
+    });
+
+    it('returns correct count after additions', () => {
+      const log = new DeletionLog();
+
+      log.recordDeletion(createMockNode({ id: 'node-1' }));
+      expect(log.size()).toBe(1);
+
+      log.recordDeletion(createMockNode({ id: 'node-2' }));
+      expect(log.size()).toBe(2);
+    });
+
+    it('returns correct count after cleanup', () => {
+      const log = new DeletionLog(1);
+
+      log.recordDeletion(createMockNode());
+      expect(log.size()).toBe(1);
+
+      vi.advanceTimersByTime(2 * 24 * 60 * 60 * 1000);
+      log.cleanup();
+
+      expect(log.size()).toBe(0);
+    });
+  });
+
+  describe('round-trip serialization', () => {
+    it('preserves all data through toJSON/fromJSON cycle', () => {
+      const original = new DeletionLog();
+
+      original.recordDeletion(
+        createMockNode({
+          id: 'product-1',
+          type: 'Product',
+          owner: 'shopify',
+        })
+      );
+
+      vi.advanceTimersByTime(1000);
+
+      original.recordDeletion(
+        createMockNode({
+          id: 'post-1',
+          type: 'BlogPost',
+          owner: 'contentful',
+        })
+      );
+
+      const json = original.toJSON();
+      const restored = DeletionLog.fromJSON(json);
+
+      expect(restored.size()).toBe(2);
+
+      const entries = restored.getDeletedSince(new Date(0));
+      expect(entries).toHaveLength(2);
+      expect(entries[0].nodeId).toBe('product-1');
+      expect(entries[1].nodeId).toBe('post-1');
+    });
+  });
+});

From 0a7061d50e555968f04cd1b887b390ef347ec49f Mon Sep 17 00:00:00 2001
From: dawidurbanski <hi@dawidurbanski.com>
Date: Mon, 22 Dec 2025 11:50:27 +0100
Subject: [PATCH 09/46] feat(core): add barrel export for sync module

---
 packages/core/src/sync/index.ts | 6 ++++++
 1 file changed, 6 insertions(+)
 create mode 100644 packages/core/src/sync/index.ts

diff --git a/packages/core/src/sync/index.ts b/packages/core/src/sync/index.ts
new file mode 100644
index 0000000..0b523b1
--- /dev/null
+++ b/packages/core/src/sync/index.ts
@@ -0,0 +1,6 @@
+export {
+  DeletionLog,
+  type DeletionLogEntry,
+  type DeletionLogData,
+  type DeletionNodeInfo,
+} from './deletion-log.js';

From 395400f54d10a1b3552806fd2a35fc5ada29c8fb Mon Sep 17 00:00:00 2001
From: dawidurbanski <hi@dawidurbanski.com>
Date: Mon, 22 Dec 2025 11:51:48 +0100
Subject: [PATCH 10/46] feat(core): extend CachedData interface with deletion
 log

---
 packages/core/src/cache/types.ts | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/packages/core/src/cache/types.ts b/packages/core/src/cache/types.ts
index 0faaf78..e4d029b 100644
--- a/packages/core/src/cache/types.ts
+++ b/packages/core/src/cache/types.ts
@@ -1,4 +1,5 @@
 import type { Node } from '../nodes/types.js';
+import type { DeletionLogData } from '../sync/index.js';
 
 /** Serializable representation of a node for cache storage */
 export type SerializedNode = Node;
@@ -9,6 +10,8 @@ export interface CachedData {
   nodes: SerializedNode[];
   /** Registered indexes: nodeType -> fieldNames[] */
   indexes: Record<string, string[]>;
+  /** Deletion log for partial sync support */
+  deletionLog?: DeletionLogData;
   /** Cache metadata */
   meta: {
     version: number;

From f3ee27604efbe7934f43285f828b93efe3699942 Mon Sep 17 00:00:00 2001
From: dawidurbanski <hi@dawidurbanski.com>
Date: Mon, 22 Dec 2025 11:54:49 +0100
Subject: [PATCH 11/46] feat(core): integrate deletion log into deleteNode
 action

---
 packages/core/src/nodes/actions/deleteNode.ts |  14 ++-
 .../unit/nodes/actions/deleteNode.test.ts     | 103 +++++++++++++++++-
 2 files changed, 114 insertions(+), 3 deletions(-)

diff --git a/packages/core/src/nodes/actions/deleteNode.ts b/packages/core/src/nodes/actions/deleteNode.ts
index 688317b..7c773af 100644
--- a/packages/core/src/nodes/actions/deleteNode.ts
+++ b/packages/core/src/nodes/actions/deleteNode.ts
@@ -1,5 +1,6 @@
 import type { Node } from '@/nodes/types.js';
 import type { NodeStore } from '@/nodes/store.js';
+import type { DeletionLog } from '@/sync/index.js';
 
 /**
  * Input for deleting a node - accepts either a node object or node ID
@@ -14,6 +15,8 @@ export interface DeleteNodeOptions {
   store: NodeStore;
   /** Whether to cascade delete all children (default: false) */
   cascade?: boolean;
+  /** Optional deletion log to record deletions for partial sync */
+  deletionLog?: DeletionLog;
 }
 
 /**
@@ -48,7 +51,7 @@ export async function deleteNode(
   input: DeleteNodeInput,
   options: DeleteNodeOptions
 ): Promise<boolean> {
-  const { store, cascade = false } = options;
+  const { store, cascade = false, deletionLog } = options;
 
   // Validate input type
   if (input === null || input === undefined) {
@@ -81,7 +84,11 @@ export async function deleteNode(
     // Create copy of children array to avoid mutation during iteration
     const childrenToDelete = [...node.children];
     for (const childId of childrenToDelete) {
-      await deleteNode(childId, { store, cascade: true });
+      const childOptions: DeleteNodeOptions = { store, cascade: true };
+      if (deletionLog) {
+        childOptions.deletionLog = deletionLog;
+      }
+      await deleteNode(childId, childOptions);
     }
   } else if (node.children && node.children.length > 0) {
     // Remove parent reference from children if not cascading
@@ -104,6 +111,9 @@ export async function deleteNode(
     }
   }
 
+  // Record deletion before removing from store
+  deletionLog?.recordDeletion(node);
+
   // Delete the node from store
   return store.delete(nodeId);
 }
diff --git a/packages/core/tests/unit/nodes/actions/deleteNode.test.ts b/packages/core/tests/unit/nodes/actions/deleteNode.test.ts
index 6a5bacf..ba25694 100644
--- a/packages/core/tests/unit/nodes/actions/deleteNode.test.ts
+++ b/packages/core/tests/unit/nodes/actions/deleteNode.test.ts
@@ -1,10 +1,11 @@
-import { beforeEach, describe, expect, it } from 'vitest';
+import { beforeEach, describe, expect, it, vi, afterEach } from 'vitest';
 import { NodeStore } from '@/nodes/store.js';
 import {
   createNode,
   deleteNode,
   type CreateNodeInput,
 } from '@/nodes/actions/index.js';
+import { DeletionLog } from '@/sync/index.js';
 
 describe('deleteNode', () => {
   let store: NodeStore;
@@ -537,4 +538,104 @@ describe('deleteNode', () => {
       }
     });
   });
+
+  describe('deletion logging', () => {
+    beforeEach(() => {
+      vi.useFakeTimers();
+      vi.setSystemTime(new Date('2024-06-15T12:00:00.000Z'));
+    });
+
+    afterEach(() => {
+      vi.useRealTimers();
+    });
+
+    it('records deletion entry when deletionLog is provided', async () => {
+      const deletionLog = new DeletionLog();
+      const input: CreateNodeInput = {
+        internal: {
+          id: 'test-1',
+          type: 'Product',
+          owner: 'shopify-plugin',
+        },
+      };
+
+      await createNode(input, { store });
+      await deleteNode('test-1', { store, deletionLog });
+
+      expect(deletionLog.size()).toBe(1);
+      const entries = deletionLog.getDeletedSince(new Date(0));
+      expect(entries[0]).toEqual({
+        nodeId: 'test-1',
+        nodeType: 'Product',
+        owner: 'shopify-plugin',
+        deletedAt: '2024-06-15T12:00:00.000Z',
+      });
+    });
+
+    it('does not throw when deletionLog is undefined', async () => {
+      const input: CreateNodeInput = {
+        internal: {
+          id: 'test-1',
+          type: 'TestNode',
+          owner: 'test-plugin',
+        },
+      };
+
+      await createNode(input, { store });
+
+      // Should not throw
+      await expect(deleteNode('test-1', { store })).resolves.toBe(true);
+    });
+
+    it('records all children when cascade deleting', async () => {
+      const deletionLog = new DeletionLog();
+
+      // Create parent
+      const parent: CreateNodeInput = {
+        internal: {
+          id: 'parent-1',
+          type: 'Parent',
+          owner: 'test-plugin',
+        },
+      };
+      await createNode(parent, { store });
+
+      // Create children
+      const child1: CreateNodeInput = {
+        internal: {
+          id: 'child-1',
+          type: 'Child',
+          owner: 'test-plugin',
+        },
+        parent: 'parent-1',
+      };
+      const child2: CreateNodeInput = {
+        internal: {
+          id: 'child-2',
+          type: 'Child',
+          owner: 'test-plugin',
+        },
+        parent: 'parent-1',
+      };
+      await createNode(child1, { store });
+      await createNode(child2, { store });
+
+      // Delete parent with cascade
+      await deleteNode('parent-1', { store, cascade: true, deletionLog });
+
+      // Should record all 3 deletions
+      expect(deletionLog.size()).toBe(3);
+      const entries = deletionLog.getDeletedSince(new Date(0));
+      const nodeIds = entries.map((e) => e.nodeId).sort();
+      expect(nodeIds).toEqual(['child-1', 'child-2', 'parent-1']);
+    });
+
+    it('does not record deletion for non-existent node', async () => {
+      const deletionLog = new DeletionLog();
+
+      await deleteNode('non-existent', { store, deletionLog });
+
+      expect(deletionLog.size()).toBe(0);
+    });
+  });
 });

From 7874d12e532bd78b1d022941a743062214b5ad5a Mon Sep 17 00:00:00 2001
From: dawidurbanski <hi@dawidurbanski.com>
Date: Mon, 22 Dec 2025 11:57:58 +0100
Subject: [PATCH 12/46] feat(core): update nodeActions to pass deletionLog to
 deleteNode

---
 packages/core/src/loader.ts                   | 10 ++++-
 packages/core/src/nodes/actions/index.ts      |  6 ++-
 .../core/src/nodes/actions/nodeActions.ts     | 37 ++++++++++++++-----
 packages/core/src/nodes/index.ts              |  1 +
 packages/core/src/webhooks/processor.ts       |  5 ++-
 5 files changed, 46 insertions(+), 13 deletions(-)

diff --git a/packages/core/src/loader.ts b/packages/core/src/loader.ts
index c83cd33..189f6d5 100644
--- a/packages/core/src/loader.ts
+++ b/packages/core/src/loader.ts
@@ -324,7 +324,10 @@ export async function loadConfigFile(
 
     // Execute sourceNodes hook with node actions bound to this plugin
     if (module.sourceNodes && options?.pluginName && options?.store) {
-      const actions = createNodeActions(options.store, options.pluginName);
+      const actions = createNodeActions({
+        store: options.store,
+        owner: options.pluginName,
+      });
       const webhookRegistry = options.webhookRegistry ?? defaultWebhookRegistry;
 
       // Create a bound registerWebhook function for this plugin
@@ -698,7 +701,10 @@ export async function loadPlugins(
             }
           }
 
-          const actions = createNodeActions(nodeStore, actualPluginName);
+          const actions = createNodeActions({
+            store: nodeStore,
+            owner: actualPluginName,
+          });
 
           // Create a bound registerWebhook function for this plugin
           const registerWebhook = (webhook: WebhookRegistration): void => {
diff --git a/packages/core/src/nodes/actions/index.ts b/packages/core/src/nodes/actions/index.ts
index 7742ad2..2867c30 100644
--- a/packages/core/src/nodes/actions/index.ts
+++ b/packages/core/src/nodes/actions/index.ts
@@ -16,4 +16,8 @@ export {
   type ExtendNodeOptions,
 } from './extendNode.js';
 
-export { createNodeActions, type NodeActions } from './nodeActions.js';
+export {
+  createNodeActions,
+  type NodeActions,
+  type CreateNodeActionsOptions,
+} from './nodeActions.js';
diff --git a/packages/core/src/nodes/actions/nodeActions.ts b/packages/core/src/nodes/actions/nodeActions.ts
index f34e093..1c191ce 100644
--- a/packages/core/src/nodes/actions/nodeActions.ts
+++ b/packages/core/src/nodes/actions/nodeActions.ts
@@ -4,6 +4,7 @@ import type { CreateNodeInput, CreateNodeOptions } from './createNode.js';
 import type { DeleteNodeInput, DeleteNodeOptions } from './deleteNode.js';
 import type { ExtendNodeData, ExtendNodeOptions } from './extendNode.js';
 import type { NodePredicate } from '@/nodes/queries.js';
+import type { DeletionLog } from '@/sync/index.js';
 import { createNode } from './createNode.js';
 import { deleteNode } from './deleteNode.js';
 import { extendNode } from './extendNode.js';
@@ -41,7 +42,7 @@ export interface NodeActions {
    */
   deleteNode: (
     input: DeleteNodeInput,
-    options?: Omit<DeleteNodeOptions, 'store'>
+    options?: Omit<DeleteNodeOptions, 'store' | 'deletionLog'>
   ) => Promise<boolean>;
 
   /**
@@ -72,28 +73,46 @@ export interface NodeActions {
   ) => T[];
 }
 
+/**
+ * Options for creating node actions
+ */
+export interface CreateNodeActionsOptions {
+  /** The node store to use for all operations */
+  store: NodeStore;
+  /** The plugin name that owns these actions */
+  owner: string;
+  /** Optional deletion log for tracking deletions */
+  deletionLog?: DeletionLog;
+}
+
 /**
  * Creates a NodeActions object bound to a specific store and owner
  * This ensures actions automatically track which plugin created which nodes
  *
- * @param store - The node store to use for all operations
- * @param owner - The plugin name that owns these actions
+ * @param options - Configuration including store, owner, and optional deletionLog
  * @returns NodeActions bound to the provided store and owner
  */
 export function createNodeActions(
-  store: NodeStore,
-  owner: string
+  options: CreateNodeActionsOptions
 ): NodeActions {
+  const { store, owner, deletionLog } = options;
+
   return {
     createNode: (
       input: CreateNodeInput,
-      options?: Omit<CreateNodeOptions, 'store' | 'owner'>
-    ) => createNode(input, { store, owner, ...options }),
+      createOptions?: Omit<CreateNodeOptions, 'store' | 'owner'>
+    ) => createNode(input, { store, owner, ...createOptions }),
 
     deleteNode: (
       input: DeleteNodeInput,
-      options?: Omit<DeleteNodeOptions, 'store'>
-    ) => deleteNode(input, { store, ...options }),
+      deleteOptions?: Omit<DeleteNodeOptions, 'store' | 'deletionLog'>
+    ) => {
+      const opts: DeleteNodeOptions = { store, ...deleteOptions };
+      if (deletionLog) {
+        opts.deletionLog = deletionLog;
+      }
+      return deleteNode(input, opts);
+    },
 
     extendNode: (nodeId: string, data: ExtendNodeData, options?) =>
       extendNode(nodeId, data, { store, ...options }),
diff --git a/packages/core/src/nodes/index.ts b/packages/core/src/nodes/index.ts
index bea4d29..97a679d 100644
--- a/packages/core/src/nodes/index.ts
+++ b/packages/core/src/nodes/index.ts
@@ -17,6 +17,7 @@ export {
   extendNode,
   createNodeActions,
   type NodeActions,
+  type CreateNodeActionsOptions,
   type CreateNodeInput,
   type CreateNodeOptions,
   type DeleteNodeInput,
diff --git a/packages/core/src/webhooks/processor.ts b/packages/core/src/webhooks/processor.ts
index 4498f2e..3301f94 100644
--- a/packages/core/src/webhooks/processor.ts
+++ b/packages/core/src/webhooks/processor.ts
@@ -105,7 +105,10 @@ async function processWebhook(webhook: QueuedWebhook): Promise<void> {
   }
 
   // Create context for the handler
-  const actions = createNodeActions(defaultStore, webhook.pluginName);
+  const actions = createNodeActions({
+    store: defaultStore,
+    owner: webhook.pluginName,
+  });
   const context: WebhookHandlerContext = {
     store: defaultStore,
     actions,

From 105f37979d937662815e51b057a08864c40d50df Mon Sep 17 00:00:00 2001
From: dawidurbanski <hi@dawidurbanski.com>
Date: Mon, 22 Dec 2025 12:00:10 +0100
Subject: [PATCH 13/46] test(core): add file-cache tests for deletion log
 persistence

---
 .../core/tests/unit/cache/file-cache.test.ts  | 100 ++++++++++++++++++
 1 file changed, 100 insertions(+)

diff --git a/packages/core/tests/unit/cache/file-cache.test.ts b/packages/core/tests/unit/cache/file-cache.test.ts
index ee533e8..ccd276d 100644
--- a/packages/core/tests/unit/cache/file-cache.test.ts
+++ b/packages/core/tests/unit/cache/file-cache.test.ts
@@ -1,6 +1,7 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import { FileCacheStorage } from '@/cache/file-cache.js';
 import type { CachedData, SerializedNode } from '@/cache/types.js';
+import type { DeletionLogData } from '@/sync/index.js';
 import * as fs from 'node:fs';
 
 /** Helper to create a valid test node */
@@ -477,3 +478,102 @@ describe('safeStringify (via FileCacheStorage.save)', () => {
     expect(content).toContain('[Circular]');
   });
 });
+
+describe('FileCacheStorage deletion log persistence', () => {
+  const mockBasePath = '/test/project';
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.spyOn(console, 'log').mockImplementation(() => {});
+    vi.spyOn(console, 'warn').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('should save deletion log when present in data', async () => {
+    vi.mocked(fs.existsSync).mockReturnValue(true);
+
+    const deletionLog: DeletionLogData = {
+      entries: [
+        {
+          nodeId: 'node-1',
+          nodeType: 'Product',
+          owner: 'shopify-plugin',
+          deletedAt: '2024-06-15T12:00:00.000Z',
+        },
+      ],
+      lastCleanup: '2024-06-15T12:00:00.000Z',
+    };
+
+    const cache = new FileCacheStorage(mockBasePath);
+    const data: CachedData = {
+      nodes: [],
+      indexes: {},
+      deletionLog,
+      meta: { version: 1, createdAt: 1000, updatedAt: 2000 },
+    };
+
+    await cache.save(data);
+
+    const [, content] = vi.mocked(fs.writeFileSync).mock.calls[0] as [
+      string,
+      string,
+    ];
+    const savedData = JSON.parse(content) as CachedData;
+    expect(savedData.deletionLog).toEqual(deletionLog);
+  });
+
+  it('should load deletion log when present in cached data', async () => {
+    const deletionLog: DeletionLogData = {
+      entries: [
+        {
+          nodeId: 'node-1',
+          nodeType: 'Product',
+          owner: 'shopify-plugin',
+          deletedAt: '2024-06-15T12:00:00.000Z',
+        },
+        {
+          nodeId: 'node-2',
+          nodeType: 'BlogPost',
+          owner: 'contentful-plugin',
+          deletedAt: '2024-06-15T13:00:00.000Z',
+        },
+      ],
+      lastCleanup: '2024-06-15T12:00:00.000Z',
+    };
+
+    const cachedData: CachedData = {
+      nodes: [],
+      indexes: {},
+      deletionLog,
+      meta: { version: 1, createdAt: 1000, updatedAt: 2000 },
+    };
+
+    vi.mocked(fs.existsSync).mockReturnValue(true);
+    vi.mocked(fs.readFileSync).mockReturnValue(JSON.stringify(cachedData));
+
+    const cache = new FileCacheStorage(mockBasePath);
+    const result = await cache.load();
+
+    expect(result?.deletionLog).toEqual(deletionLog);
+  });
+
+  it('should return undefined deletionLog when not present (backwards compatibility)', async () => {
+    const cachedData: CachedData = {
+      nodes: [],
+      indexes: {},
+      // deletionLog is not present
+      meta: { version: 1, createdAt: 1000, updatedAt: 2000 },
+    };
+
+    vi.mocked(fs.existsSync).mockReturnValue(true);
+    vi.mocked(fs.readFileSync).mockReturnValue(JSON.stringify(cachedData));
+
+    const cache = new FileCacheStorage(mockBasePath);
+    const result = await cache.load();
+
+    expect(result?.deletionLog).toBeUndefined();
+  });
+});

From 185612943d22e007debc63c1d0639ecb503107ea Mon Sep 17 00:00:00 2001
From: dawidurbanski <hi@dawidurbanski.com>
Date: Mon, 22 Dec 2025 12:01:31 +0100
Subject: [PATCH 14/46] feat(core): export deletion log from core package

---
 packages/core/src/index.ts | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index bf79413..739dfad 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -90,6 +90,14 @@ export {
   type SerializedNode,
 } from './cache/index.js';
 
+// Re-export sync utilities (deletion log for partial sync)
+export {
+  DeletionLog,
+  type DeletionLogEntry,
+  type DeletionLogData,
+  type DeletionNodeInfo,
+} from './sync/index.js';
+
 // Re-export env utilities
 export { loadEnv, type LoadEnvOptions, type LoadEnvResult } from './env.js';
 

From fc8bec85dff5f36945e6456e0331450606ba54ae Mon Sep 17 00:00:00 2001
From: dawidurbanski <hi@dawidurbanski.com>
Date: Mon, 22 Dec 2025 17:03:26 +0100
Subject: [PATCH 15/46] feat(core): add default webhook handler for
 standardized CRUD operations

Add a default webhook handler system that provides a standardized endpoint
for create/update/delete/upsert operations on nodes. This enables external
systems to sync data with UDL using a consistent payload format.

Key features:
- DefaultWebhookPayload type for standardized request format
- createDefaultWebhookHandler() factory with idField support for custom lookups
- registerDefaultWebhook/registerDefaultWebhooks utilities for auto-registration
- Per-plugin configuration with path overrides and disable options
- Handles both string and numeric ID lookups for flexibility

The handler supports looking up existing nodes by a custom idField (e.g.,
externalId, contentfulId) instead of internal IDs, enabling seamless
integration with external data sources.
---
 packages/core/src/webhooks/default-handler.ts | 365 +++++++++
 packages/core/src/webhooks/index.ts           |  15 +
 .../core/src/webhooks/register-default.ts     | 132 ++++
 packages/core/src/webhooks/types.ts           |  85 ++
 .../unit/webhooks/default-handler.test.ts     | 727 ++++++++++++++++++
 .../unit/webhooks/register-default.test.ts    | 212 +++++
 6 files changed, 1536 insertions(+)
 create mode 100644 packages/core/src/webhooks/default-handler.ts
 create mode 100644 packages/core/src/webhooks/register-default.ts
 create mode 100644 packages/core/tests/unit/webhooks/default-handler.test.ts
 create mode 100644 packages/core/tests/unit/webhooks/register-default.test.ts

diff --git a/packages/core/src/webhooks/default-handler.ts b/packages/core/src/webhooks/default-handler.ts
new file mode 100644
index 0000000..e01a40b
--- /dev/null
+++ b/packages/core/src/webhooks/default-handler.ts
@@ -0,0 +1,365 @@
+/**
+ * Default Webhook Handler
+ *
+ * Provides a standardized webhook handler for CRUD operations on nodes.
+ * Auto-registered for plugins when `defaultWebhook` config is enabled.
+ */
+
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { WebhookHandlerContext, DefaultWebhookPayload } from './types.js';
+import type { Node } from '@/nodes/types.js';
+import { createNodeId } from '@/nodes/utils/index.js';
+
+/**
+ * Default path for webhook endpoints when not specified.
+ */
+export const DEFAULT_WEBHOOK_PATH = 'sync';
+
+/**
+ * Options for creating a default webhook handler.
+ */
+export interface DefaultWebhookHandlerOptions {
+  /**
+   * The plugin's unique identifier field for nodes.
+   * When specified, the `nodeId` in webhook payloads is matched against this field
+   * instead of the internal node ID.
+   *
+   * This should match the plugin's `idField` config.
+   *
+   * @example 'externalId' - Match nodeId against the externalId field
+   */
+  idField?: string;
+}
+
+/**
+ * Validate the webhook payload structure.
+ */
+function validatePayload(body: unknown): body is DefaultWebhookPayload {
+  if (!body || typeof body !== 'object') return false;
+  const payload = body as Record<string, unknown>;
+
+  const operation = payload['operation'];
+  if (!['create', 'update', 'delete', 'upsert'].includes(operation as string)) {
+    return false;
+  }
+
+  const nodeId = payload['nodeId'];
+  if (typeof nodeId !== 'string' || !nodeId) {
+    return false;
+  }
+
+  const nodeType = payload['nodeType'];
+  if (typeof nodeType !== 'string' || !nodeType) {
+    return false;
+  }
+
+  // data is required for create/update/upsert, optional for delete
+  if (operation !== 'delete') {
+    const data = payload['data'];
+    if (!data || typeof data !== 'object') {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Create the default webhook handler for a plugin.
+ *
+ * The handler accepts standardized payloads with CRUD operations:
+ * - `create`: Create a new node (returns 409 if exists)
+ * - `update`: Update an existing node (returns 404 if doesn't exist)
+ * - `delete`: Delete a node (returns 404 if doesn't exist)
+ * - `upsert`: Create or update a node (always succeeds)
+ *
+ * @param pluginName - The name of the plugin (used as node owner)
+ * @param options - Handler configuration options
+ * @returns The webhook handler function
+ *
+ * @example
+ * ```typescript
+ * // Payload format:
+ * {
+ *   "operation": "upsert",
+ *   "nodeId": "product-123",
+ *   "nodeType": "Product",
+ *   "data": { "title": "New Product", "price": 99.99 }
+ * }
+ *
+ * // With idField: 'externalId', nodeId matches against externalId field:
+ * {
+ *   "operation": "update",
+ *   "nodeId": "123",  // Matches nodes where externalId = 123
+ *   "nodeType": "Product",
+ *   "data": { "title": "Updated Product" }
+ * }
+ * ```
+ */
+export function createDefaultWebhookHandler(
+  pluginName: string,
+  options: DefaultWebhookHandlerOptions = {}
+) {
+  const { idField } = options;
+
+  /**
+   * Find an existing node by nodeId.
+   * If idField is set, searches by that field; otherwise by internal ID.
+   * Tries both string and numeric lookups since JSON always sends strings but
+   * the stored value might be a number.
+   */
+  function findExistingNode(
+    context: WebhookHandlerContext,
+    nodeType: string,
+    nodeId: string
+  ): Node | undefined {
+    const { store, actions } = context;
+
+    if (idField) {
+      // Ensure the index is registered for this field
+      store.registerIndex(nodeType, idField);
+
+      // Try index lookup first (O(1) if indexed)
+      // Try string lookup
+      let node = store.getByField(nodeType, idField, nodeId) as
+        | Node
+        | undefined;
+      if (node) return node;
+
+      // Try numeric lookup if nodeId looks like a number
+      const numericId = Number(nodeId);
+      if (!isNaN(numericId)) {
+        node = store.getByField(nodeType, idField, numericId) as
+          | Node
+          | undefined;
+        if (node) return node;
+      }
+
+      // Fallback: linear scan for nodes created before index was registered
+      // This handles the case where nodes exist but weren't indexed
+      const allNodes = store.getByType(nodeType);
+      for (const n of allNodes) {
+        const fieldValue = (n as unknown as Record<string, unknown>)[idField];
+        // Compare with both string and numeric versions
+        if (fieldValue === nodeId || fieldValue === numericId) {
+          return n;
+        }
+      }
+
+      return undefined;
+    }
+
+    // Default: look up by internal ID
+    return actions.getNode(nodeId);
+  }
+
+  /**
+   * Get the internal node ID to use for create/update operations.
+   * If an existing node is found, uses its ID; otherwise generates a new one.
+   */
+  function getInternalNodeId(
+    existing: Node | undefined,
+    nodeType: string,
+    nodeId: string
+  ): string {
+    if (existing) {
+      return existing.internal.id;
+    }
+
+    // Generate a consistent internal ID using the same pattern as plugins
+    if (idField) {
+      return createNodeId(nodeType, String(nodeId));
+    }
+
+    // When not using idField, nodeId is already the internal ID
+    return nodeId;
+  }
+
+  return async function defaultWebhookHandler(
+    _req: IncomingMessage,
+    res: ServerResponse,
+    context: WebhookHandlerContext
+  ): Promise<void> {
+    const { body, actions } = context;
+
+    // Validate payload
+    if (!validatePayload(body)) {
+      console.warn(
+        `⚠️ Default webhook handler [${pluginName}]: Invalid payload received`,
+        JSON.stringify(body, null, 2)
+      );
+      res.writeHead(400, { 'Content-Type': 'application/json' });
+      res.end(
+        JSON.stringify({
+          error: 'Invalid payload',
+          expected: {
+            operation: 'create | update | delete | upsert',
+            nodeId: 'string',
+            nodeType: 'string',
+            data: 'object (required for create/update/upsert)',
+          },
+        })
+      );
+      return;
+    }
+
+    const { operation, nodeId, nodeType, data } = body;
+    const lookupInfo = idField ? ` (idField: ${idField}=${nodeId})` : '';
+
+    const nodeData = data;
+
+    try {
+      switch (operation) {
+        case 'create': {
+          // Check if node already exists
+          const existing = findExistingNode(context, nodeType, nodeId);
+          if (existing) {
+            console.log(
+              `⚠️ Default webhook [${pluginName}]: Node already exists: ${nodeId}${lookupInfo}`
+            );
+            res.writeHead(409, { 'Content-Type': 'application/json' });
+            res.end(
+              JSON.stringify({
+                error: 'Node already exists',
+                nodeId,
+              })
+            );
+            return;
+          }
+
+          const internalId = getInternalNodeId(existing, nodeType, nodeId);
+          await actions.createNode({
+            internal: {
+              id: internalId,
+              type: nodeType,
+              owner: pluginName,
+            },
+            ...nodeData,
+          });
+
+          console.log(
+            `✅ Default webhook [${pluginName}]: Created node ${nodeType}:${internalId}${lookupInfo}`
+          );
+          res.writeHead(201, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ created: true, nodeId, internalId }));
+          break;
+        }
+
+        case 'update': {
+          // Check if node exists
+          const existing = findExistingNode(context, nodeType, nodeId);
+          if (!existing) {
+            console.log(
+              `⚠️ Default webhook [${pluginName}]: Node not found for update: ${nodeId}${lookupInfo}`
+            );
+            res.writeHead(404, { 'Content-Type': 'application/json' });
+            res.end(
+              JSON.stringify({
+                error: 'Node not found',
+                nodeId,
+                idField: idField || 'internal.id',
+              })
+            );
+            return;
+          }
+
+          const internalId = existing.internal.id;
+          // Use createNode which handles updates via contentDigest
+          await actions.createNode({
+            internal: {
+              id: internalId,
+              type: nodeType,
+              owner: pluginName,
+            },
+            ...nodeData,
+          });
+
+          console.log(
+            `✅ Default webhook [${pluginName}]: Updated node ${nodeType}:${internalId}${lookupInfo}`
+          );
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ updated: true, nodeId, internalId }));
+          break;
+        }
+
+        case 'upsert': {
+          // Find existing node to get/generate the internal ID
+          const existing = findExistingNode(context, nodeType, nodeId);
+          const internalId = getInternalNodeId(existing, nodeType, nodeId);
+          const wasUpdate = !!existing;
+
+          await actions.createNode({
+            internal: {
+              id: internalId,
+              type: nodeType,
+              owner: pluginName,
+            },
+            ...nodeData,
+          });
+
+          console.log(
+            `✅ Default webhook [${pluginName}]: ${wasUpdate ? 'Updated' : 'Created'} node ${nodeType}:${internalId}${lookupInfo}`
+          );
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(
+            JSON.stringify({ upserted: true, nodeId, internalId, wasUpdate })
+          );
+          break;
+        }
+
+        case 'delete': {
+          // Find the node to get its internal ID
+          const existing = findExistingNode(context, nodeType, nodeId);
+          if (!existing) {
+            console.log(
+              `⚠️ Default webhook [${pluginName}]: Node not found for delete: ${nodeId}${lookupInfo}`
+            );
+            res.writeHead(404, { 'Content-Type': 'application/json' });
+            res.end(
+              JSON.stringify({
+                error: 'Node not found',
+                nodeId,
+                idField: idField || 'internal.id',
+              })
+            );
+            return;
+          }
+
+          const internalId = existing.internal.id;
+          const deleted = await actions.deleteNode(internalId);
+
+          if (deleted) {
+            console.log(
+              `✅ Default webhook [${pluginName}]: Deleted node ${nodeType}:${internalId}${lookupInfo}`
+            );
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ deleted: true, nodeId, internalId }));
+          } else {
+            // This shouldn't happen if findExistingNode returned a node
+            console.log(
+              `⚠️ Default webhook [${pluginName}]: Delete failed for node: ${internalId}`
+            );
+            res.writeHead(500, { 'Content-Type': 'application/json' });
+            res.end(
+              JSON.stringify({
+                error: 'Delete failed',
+                nodeId,
+                internalId,
+              })
+            );
+          }
+          break;
+        }
+      }
+    } catch (error) {
+      console.error(`Default webhook handler error for ${pluginName}:`, error);
+      res.writeHead(500, { 'Content-Type': 'application/json' });
+      res.end(
+        JSON.stringify({
+          error: 'Internal server error',
+          message: error instanceof Error ? error.message : 'Unknown error',
+        })
+      );
+    }
+  };
+}
diff --git a/packages/core/src/webhooks/index.ts b/packages/core/src/webhooks/index.ts
index 4489142..608fea4 100644
--- a/packages/core/src/webhooks/index.ts
+++ b/packages/core/src/webhooks/index.ts
@@ -12,6 +12,9 @@ export type {
   WebhookHandlerFn,
   WebhookHandlerContext,
   WebhookHandler,
+  DefaultWebhookPayload,
+  DefaultWebhookHandlerConfig,
+  PluginDefaultWebhookConfig,
 } from './types.js';
 
 // Registry
@@ -67,3 +70,15 @@ export type {
 } from './outbound.js';
 
 export { OutboundWebhookManager } from './outbound.js';
+
+// Default Handler
+export type { DefaultWebhookHandlerOptions } from './default-handler.js';
+export {
+  createDefaultWebhookHandler,
+  DEFAULT_WEBHOOK_PATH,
+} from './default-handler.js';
+
+export {
+  registerDefaultWebhook,
+  registerDefaultWebhooks,
+} from './register-default.js';
diff --git a/packages/core/src/webhooks/register-default.ts b/packages/core/src/webhooks/register-default.ts
new file mode 100644
index 0000000..5ce4cfa
--- /dev/null
+++ b/packages/core/src/webhooks/register-default.ts
@@ -0,0 +1,132 @@
+/**
+ * Default Webhook Registration Utility
+ *
+ * Provides functions to automatically register default webhook handlers
+ * for plugins based on configuration.
+ */
+
+import type { WebhookRegistry } from './registry.js';
+import type { DefaultWebhookHandlerConfig } from './types.js';
+import {
+  createDefaultWebhookHandler,
+  DEFAULT_WEBHOOK_PATH,
+} from './default-handler.js';
+
+/**
+ * Register a default webhook handler for a plugin if enabled in configuration.
+ *
+ * This function checks the `defaultWebhook` configuration and registers
+ * a standardized webhook handler for the specified plugin. It respects:
+ * - Global enable/disable setting
+ * - Per-plugin enable/disable setting
+ * - Custom paths (global and per-plugin)
+ * - Existing custom handlers (won't overwrite)
+ * - Plugin's idField for node lookups
+ *
+ * @param registry - The webhook registry to register with
+ * @param pluginName - The plugin name to register for
+ * @param config - The default webhook configuration
+ * @param pluginIdField - The plugin's configured idField (from plugin's udl.config)
+ * @returns The path that was registered, or null if not registered
+ *
+ * @example
+ * ```typescript
+ * const path = registerDefaultWebhook(registry, 'contentful', {
+ *   enabled: true,
+ *   path: 'sync',
+ * }, 'contentfulId');
+ * // path = 'sync' if registered, null if skipped
+ * ```
+ */
+export function registerDefaultWebhook(
+  registry: WebhookRegistry,
+  pluginName: string,
+  config: DefaultWebhookHandlerConfig | undefined,
+  pluginIdField?: string
+): string | null {
+  // If config is not present, default handlers are disabled
+  if (!config) {
+    return null;
+  }
+
+  // Check if explicitly disabled globally
+  if (config.enabled === false) {
+    return null;
+  }
+
+  // Check per-plugin configuration
+  const pluginConfig = config.plugins?.[pluginName];
+
+  // If plugin is explicitly disabled
+  if (pluginConfig === false) {
+    console.log(`📭 Default webhook disabled for plugin: ${pluginName}`);
+    return null;
+  }
+
+  // Determine the path to use
+  const globalPath = config.path ?? DEFAULT_WEBHOOK_PATH;
+  const path =
+    typeof pluginConfig === 'object' && pluginConfig.path
+      ? pluginConfig.path
+      : globalPath;
+
+  // Check if handler already exists for this path (don't overwrite custom handlers)
+  if (registry.has(pluginName, path)) {
+    console.log(
+      `📌 Plugin ${pluginName} already has handler for '${path}', skipping default registration`
+    );
+    return null;
+  }
+
+  // Register the default handler using the plugin's idField
+  registry.register(pluginName, {
+    path,
+    handler: createDefaultWebhookHandler(
+      pluginName,
+      pluginIdField ? { idField: pluginIdField } : {}
+    ),
+    description: `Default UDL sync handler for ${pluginName}${pluginIdField ? ` (idField: ${pluginIdField})` : ''}`,
+  });
+
+  const lookupInfo = pluginIdField ? ` (idField: ${pluginIdField})` : '';
+  console.log(
+    `📬 Default webhook registered: /_webhooks/${pluginName}/${path}${lookupInfo}`
+  );
+  return path;
+}
+
+/**
+ * Register default webhooks for multiple plugins.
+ *
+ * Convenience function to register default handlers for all plugins
+ * in a single call.
+ *
+ * @param registry - The webhook registry to register with
+ * @param pluginNames - Array of plugin names to register
+ * @param config - The default webhook configuration
+ * @returns Map of plugin name to registered path (or null if not registered)
+ *
+ * @example
+ * ```typescript
+ * const results = registerDefaultWebhooks(
+ *   registry,
+ *   ['contentful', 'shopify', 'custom-plugin'],
+ *   { enabled: true }
+ * );
+ * // results: Map { 'contentful' => 'sync', 'shopify' => 'sync', ... }
+ * ```
+ */
+export function registerDefaultWebhooks(
+  registry: WebhookRegistry,
+  pluginNames: string[],
+  config: DefaultWebhookHandlerConfig | undefined
+): Map<string, string | null> {
+  const results = new Map<string, string | null>();
+
+  for (const pluginName of pluginNames) {
+    const path = registerDefaultWebhook(registry, pluginName, config);
+    results.set(pluginName, path);
+  }
+
+  return results;
+}
diff --git a/packages/core/src/webhooks/types.ts b/packages/core/src/webhooks/types.ts
index 51d8980..dbcd7a8 100644
--- a/packages/core/src/webhooks/types.ts
+++ b/packages/core/src/webhooks/types.ts
@@ -122,3 +122,88 @@ export interface WebhookHandler extends WebhookRegistration {
   /** Name of the plugin that registered this webhook */
   pluginName: string;
 }
+
+/**
+ * Standardized webhook payload for default handlers.
+ * This payload format is used by the auto-registered default webhook handlers.
+ */
+export interface DefaultWebhookPayload {
+  /**
+   * The operation to perform on the node.
+   * - 'create': Create a new node (fails if exists)
+   * - 'update': Update an existing node (fails if doesn't exist)
+   * - 'delete': Delete a node
+   * - 'upsert': Create or update a node (always succeeds)
+   */
+  operation: 'create' | 'update' | 'delete' | 'upsert';
+
+  /**
+   * The unique identifier for the node.
+   */
+  nodeId: string;
+
+  /**
+   * The type of node (e.g., 'Product', 'Article').
+   */
+  nodeType: string;
+
+  /**
+   * The node data for create/update/upsert operations.
+   * Not required for delete operations.
+   */
+  data?: Record<string, unknown>;
+}
+
+/**
+ * Per-plugin configuration for default webhook handler.
+ */
+export interface PluginDefaultWebhookConfig {
+  /**
+   * Custom path for this plugin's default webhook.
+   * If not specified, uses the global default path.
+   */
+  path?: string;
+}
+
+/**
+ * Configuration for the default webhook handler feature.
+ * When enabled, automatically registers a standardized webhook endpoint
+ * for each loaded plugin that has an `idField` configured.
+ *
+ * The webhook handler uses the plugin's `idField` config to look up existing
+ * nodes when processing update/delete operations.
+ *
+ * @example
+ * ```typescript
+ * defineConfig({
+ *   defaultWebhook: {
+ *     enabled: true,
+ *     path: 'sync',
+ *     plugins: {
+ *       'contentful': { path: 'content-sync' },
+ *       'legacy-plugin': false,  // Disable for this plugin
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export interface DefaultWebhookHandlerConfig {
+  /**
+   * Whether default handlers are enabled.
+   * @default true (when this config object is present)
+   */
+  enabled?: boolean;
+
+  /**
+   * The default path for all plugin webhooks.
+   * @default 'sync'
+   */
+  path?: string;
+
+  /**
+   * Per-plugin configuration overrides.
+   * Set to `false` to disable default handler for a specific plugin.
+   * Set to `{ path: 'custom' }` to use a custom path for that plugin.
+   */
+  plugins?: Record<string, PluginDefaultWebhookConfig | false>;
+}
diff --git a/packages/core/tests/unit/webhooks/default-handler.test.ts b/packages/core/tests/unit/webhooks/default-handler.test.ts
new file mode 100644
index 0000000..1d0d763
--- /dev/null
+++ b/packages/core/tests/unit/webhooks/default-handler.test.ts
@@ -0,0 +1,727 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import {
+  createDefaultWebhookHandler,
+  DEFAULT_WEBHOOK_PATH,
+} from '@/webhooks/default-handler.js';
+import { NodeStore } from '@/nodes/store.js';
+import { createNodeActions } from '@/nodes/actions/index.js';
+import type { WebhookHandlerContext } from '@/webhooks/types.js';
+import type { ServerResponse } from 'node:http';
+
+describe('DEFAULT_WEBHOOK_PATH', () => {
+  it('should be "sync"', () => {
+    expect(DEFAULT_WEBHOOK_PATH).toBe('sync');
+  });
+});
+
+describe('createDefaultWebhookHandler', () => {
+  let store: NodeStore;
+  let handler: ReturnType<typeof createDefaultWebhookHandler>;
+
+  function createMockContext(body: unknown): WebhookHandlerContext {
+    const actions = createNodeActions({ store, owner: 'test-plugin' });
+    return {
+      store,
+      actions,
+      rawBody: Buffer.from(JSON.stringify(body)),
+      body,
+    };
+  }
+
+  function createMockResponse(): ServerResponse & {
+    getStatusCode: () => number;
+    getBody: () => string;
+    getHeaders: () => Record<string, string>;
+  } {
+    let statusCode = 200;
+    let responseBody = '';
+    const headers: Record<string, string> = {};
+
+    return {
+      writeHead(code: number, headersArg?: Record<string, string>) {
+        statusCode = code;
+        if (headersArg) {
+          Object.assign(headers, headersArg);
+        }
+        return this;
+      },
+      end(body?: string) {
+        responseBody = body || '';
+      },
+      getStatusCode: () => statusCode,
+      getBody: () => responseBody,
+      getHeaders: () => headers,
+    } as unknown as ServerResponse & {
+      getStatusCode: () => number;
+      getBody: () => string;
+      getHeaders: () => Record<string, string>;
+    };
+  }
+
+  beforeEach(() => {
+    store = new NodeStore();
+    handler = createDefaultWebhookHandler('test-plugin');
+  });
+
+  describe('upsert operation', () => {
+    it('should create a new node', async () => {
+      const context = createMockContext({
+        operation: 'upsert',
+        nodeId: 'product-1',
+        nodeType: 'Product',
+        data: { title: 'Test Product', price: 99 },
+      });
+      const res = createMockResponse();
+
+      await handler(null as never, res, context);
+
+      expect(res.getStatusCode()).toBe(200);
+      expect(JSON.parse(res.getBody())).toMatchObject({
+        upserted: true,
+        nodeId: 'product-1',
+      });
+
+      const node = store.get('product-1');
+      expect(node).toBeDefined();
+      expect(node!.internal.type).toBe('Product');
+      expect(node!.internal.owner).toBe('test-plugin');
+      expect((node as Record<string, unknown>).title).toBe('Test Product');
+      expect((node as Record<string, unknown>).price).toBe(99);
+    });
+
+    it('should update an existing node', async () => {
+      // First create
+      await handler(
+        null as never,
+        createMockResponse(),
+        createMockContext({
+          operation: 'upsert',
+          nodeId: 'product-1',
+          nodeType: 'Product',
+          data: { title: 'Original' },
+        })
+      );
+
+      // Then update
+      const res = createMockResponse();
+      await handler(
+        null as never,
+        res,
+        createMockContext({
+          operation: 'upsert',
+          nodeId: 'product-1',
+          nodeType: 'Product',
+          data: { title: 'Updated' },
+        })
+      );
+
+      expect(res.getStatusCode()).toBe(200);
+      const node = store.get('product-1');
+      expect((node as Record<string, unknown>).title).toBe('Updated');
+    });
+  });
+
+  describe('create operation', () => {
+    it('should create a new node', async () => {
+      const res = createMockResponse();
+      await handler(
+        null as never,
+        res,
+        createMockContext({
+          operation: 'create',
+          nodeId: 'article-1',
+          nodeType: 'Article',
+          data: { title: 'New Article' },
+        })
+      );
+
+      expect(res.getStatusCode()).toBe(201);
+      expect(JSON.parse(res.getBody())).toMatchObject({
+        created: true,
+        nodeId: 'article-1',
+      });
+      expect(store.get('article-1')).toBeDefined();
+    });
+
+    it('should return 409 if node already exists', async () => {
+      // Create first
+      await handler(
+        null as never,
+        createMockResponse(),
+        createMockContext({
+          operation: 'create',
+          nodeId: 'article-1',
+          nodeType: 'Article',
+          data: { title: 'First' },
+        })
+      );
+
+      // Try to create again
+      const res = createMockResponse();
+      await handler(
+        null as never,
+        res,
+        createMockContext({
+          operation: 'create',
+          nodeId: 'article-1',
+          nodeType: 'Article',
+          data: { title: 'Second' },
+        })
+      );
+
+      expect(res.getStatusCode()).toBe(409);
+      expect(JSON.parse(res.getBody())).toEqual({
+        error: 'Node already exists',
+        nodeId: 'article-1',
+      });
+    });
+  });
+
+  describe('update operation', () => {
+    it('should update an existing node', async () => {
+      // First create
+      await handler(
+        null as never,
+        createMockResponse(),
+        createMockContext({
+          operation: 'upsert',
+          nodeId: 'item-1',
+          nodeType: 'Item',
+          data: { name: 'Original' },
+        })
+      );
+
+      // Then update
+      const res = createMockResponse();
+      await handler(
+        null as never,
+        res,
+        createMockContext({
+          operation: 'update',
+          nodeId: 'item-1',
+          nodeType: 'Item',
+          data: { name: 'Updated' },
+        })
+      );
+
+      expect(res.getStatusCode()).toBe(200);
+      expect(JSON.parse(res.getBody())).toMatchObject({
+        updated: true,
+        nodeId: 'item-1',
+      });
+      const node = store.get('item-1');
+      expect((node as Record<string, unknown>).name).toBe('Updated');
+    });
+
+    it('should return 404 if node does not exist', async () => {
+      const res = createMockResponse();
+      await handler(
+        null as never,
+        res,
+        createMockContext({
+          operation: 'update',
+          nodeId: 'nonexistent',
+          nodeType: 'Item',
+          data: { name: 'Test' },
+        })
+      );
+
+      expect(res.getStatusCode()).toBe(404);
+      expect(JSON.parse(res.getBody())).toMatchObject({
+        error: 'Node not found',
+        nodeId: 'nonexistent',
+      });
+    });
+  });
+
+  describe('delete operation', () => {
+    it('should delete an existing node', async () => {
+      // First create
+      await handler(
+        null as never,
+        createMockResponse(),
+        createMockContext({
+          operation: 'upsert',
+          nodeId: 'delete-me',
+          nodeType: 'Test',
+          data: { foo: 'bar' },
+        })
+      );
+
+      expect(store.get('delete-me')).toBeDefined();
+
+      // Then delete
+      const res = createMockResponse();
+      await handler(
+        null as never,
+        res,
+        createMockContext({
+          operation: 'delete',
+          nodeId: 'delete-me',
+          nodeType: 'Test',
+        })
+      );
+
+      expect(res.getStatusCode()).toBe(200);
+      expect(JSON.parse(res.getBody())).toMatchObject({
+        deleted: true,
+        nodeId: 'delete-me',
+      });
+      expect(store.get('delete-me')).toBeUndefined();
+    });
+
+    it('should return 404 if node does not exist', async () => {
+      const res = createMockResponse();
+      await handler(
+        null as never,
+        res,
+        createMockContext({
+          operation: 'delete',
+          nodeId: 'nonexistent',
+          nodeType: 'Test',
+        })
+      );
+
+      expect(res.getStatusCode()).toBe(404);
+      expect(JSON.parse(res.getBody())).toMatchObject({
+        error: 'Node not found',
+        nodeId: 'nonexistent',
+      });
+    });
+  });
+
+  describe('payload validation', () => {
+    it('should reject null body', async () => {
+      const res = createMockResponse();
+      await handler(null as never, res, {
+        ...createMockContext({}),
+        body: null,
+      });
+
+      expect(res.getStatusCode()).toBe(400);
+      expect(JSON.parse(res.getBody()).error).toBe('Invalid payload');
+    });
+
+    it('should reject invalid operation', async () => {
+      const res = createMockResponse();
+      await handler(
+        null as never,
+        res,
+        createMockContext({
+          operation: 'invalid',
+          nodeId: 'test',
+          nodeType: 'Test',
+        })
+      );
+
+      expect(res.getStatusCode()).toBe(400);
+    });
+
+    it('should reject missing nodeId', async () => {
+      const res = createMockResponse();
+      await handler(
+        null as never,
+        res,
+        createMockContext({
+          operation: 'upsert',
+          nodeType: 'Test',
+          data: {},
+        })
+      );
+
+      expect(res.getStatusCode()).toBe(400);
+    });
+
+    it('should reject empty nodeId', async () => {
+      const res = createMockResponse();
+      await handler(
+        null as never,
+        res,
+        createMockContext({
+          operation: 'upsert',
+          nodeId: '',
+          nodeType: 'Test',
+          data: {},
+        })
+      );
+
+      expect(res.getStatusCode()).toBe(400);
+    });
+
+    it('should reject missing nodeType', async () => {
+      const res = createMockResponse();
+      await handler(
+        null as never,
+        res,
+        createMockContext({
+          operation: 'upsert',
+          nodeId: 'test',
+          data: {},
+        })
+      );
+
+      expect(res.getStatusCode()).toBe(400);
+    });
+
+    it('should reject missing data for create', async () => {
+      const res = createMockResponse();
+      await handler(
+        null as never,
+        res,
+        createMockContext({
+          operation: 'create',
+          nodeId: 'test',
+          nodeType: 'Test',
+        })
+      );
+
+      expect(res.getStatusCode()).toBe(400);
+    });
+
+    it('should reject missing data for upsert', async () => {
+      const res = createMockResponse();
+      await handler(
+        null as never,
+        res,
+        createMockContext({
+          operation: 'upsert',
+          nodeId: 'test',
+          nodeType: 'Test',
+        })
+      );
+
+      expect(res.getStatusCode()).toBe(400);
+    });
+
+    it('should allow missing data for delete', async () => {
+      // First create a node
+      await handler(
+        null as never,
+        createMockResponse(),
+        createMockContext({
+          operation: 'upsert',
+          nodeId: 'to-delete',
+          nodeType: 'Test',
+          data: {},
+        })
+      );
+
+      // Then delete without data
+      const res = createMockResponse();
+      await handler(
+        null as never,
+        res,
+        createMockContext({
+          operation: 'delete',
+          nodeId: 'to-delete',
+          nodeType: 'Test',
+        })
+      );
+
+      expect(res.getStatusCode()).toBe(200);
+    });
+  });
+
+  describe('error handling', () => {
+    it('should handle internal errors gracefully', async () => {
+      const context = createMockContext({
+        operation: 'upsert',
+        nodeId: 'test',
+        nodeType: 'Test',
+        data: { foo: 'bar' },
+      });
+
+      // Mock createNode to throw
+      context.actions.createNode = vi
+        .fn()
+        .mockRejectedValue(new Error('DB error'));
+
+      const res = createMockResponse();
+      await handler(null as never, res, context);
+
+      expect(res.getStatusCode()).toBe(500);
+      expect(JSON.parse(res.getBody())).toEqual({
+        error: 'Internal server error',
+        message: 'DB error',
+      });
+    });
+  });
+
+  describe('pluginName as owner', () => {
+    it('should use pluginName as node owner', async () => {
+      const customHandler = createDefaultWebhookHandler('my-custom-plugin');
+
+      const customStore = new NodeStore();
+      const actions = createNodeActions({
+        store: customStore,
+        owner: 'my-custom-plugin',
+      });
+
+      await customHandler(null as never, createMockResponse(), {
+        store: customStore,
+        actions,
+        rawBody: Buffer.from('{}'),
+        body: {
+          operation: 'upsert',
+          nodeId: 'node-1',
+          nodeType: 'Test',
+          data: {},
+        },
+      });
+
+      const node = customStore.get('node-1');
+      expect(node!.internal.owner).toBe('my-custom-plugin');
+    });
+  });
+
+  describe('idField option', () => {
+    it('should find nodes by custom field for update', async () => {
+      const customStore = new NodeStore();
+      const actions = createNodeActions({
+        store: customStore,
+        owner: 'test-plugin',
+      });
+
+      // Register index for idField
+      customStore.registerIndex('Todo', 'externalId');
+
+      // Pre-create a node with an internal ID different from external ID
+      // Note: externalId stored as string since webhook sends strings
+      customStore.set({
+        internal: {
+          id: 'Todo-123', // Internal ID
+          type: 'Todo',
+          owner: 'test-plugin',
+          contentDigest: 'abc',
+        },
+        externalId: '123', // Stored as string to match webhook lookup
+        title: 'Original Title',
+      });
+
+      // Create handler with idField
+      const lookupHandler = createDefaultWebhookHandler('test-plugin', {
+        idField: 'externalId',
+      });
+
+      const res = createMockResponse();
+      await lookupHandler(null as never, res, {
+        store: customStore,
+        actions,
+        rawBody: Buffer.from('{}'),
+        body: {
+          operation: 'update',
+          nodeId: '123', // Using external ID (string)
+          nodeType: 'Todo',
+          data: { externalId: '123', title: 'Updated Title' },
+        },
+      });
+
+      expect(res.getStatusCode()).toBe(200);
+      expect(JSON.parse(res.getBody())).toMatchObject({
+        updated: true,
+        nodeId: '123',
+        internalId: 'Todo-123',
+      });
+
+      // Check that the node was updated
+      const node = customStore.get('Todo-123');
+      expect((node as Record<string, unknown>).title).toBe('Updated Title');
+    });
+
+    it('should find nodes by custom field for delete', async () => {
+      const customStore = new NodeStore();
+      const actions = createNodeActions({
+        store: customStore,
+        owner: 'test-plugin',
+      });
+
+      // Register index for idField
+      customStore.registerIndex('Todo', 'externalId');
+
+      // Pre-create a node (externalId as string to match webhook lookup)
+      customStore.set({
+        internal: {
+          id: 'Todo-456',
+          type: 'Todo',
+          owner: 'test-plugin',
+          contentDigest: 'xyz',
+        },
+        externalId: '456',
+        title: 'To Delete',
+      });
+
+      const lookupHandler = createDefaultWebhookHandler('test-plugin', {
+        idField: 'externalId',
+      });
+
+      const res = createMockResponse();
+      await lookupHandler(null as never, res, {
+        store: customStore,
+        actions,
+        rawBody: Buffer.from('{}'),
+        body: {
+          operation: 'delete',
+          nodeId: '456', // Using external ID (string)
+          nodeType: 'Todo',
+        },
+      });
+
+      expect(res.getStatusCode()).toBe(200);
+      expect(JSON.parse(res.getBody())).toMatchObject({
+        deleted: true,
+        nodeId: '456',
+        internalId: 'Todo-456',
+      });
+
+      // Verify node was deleted
+      expect(customStore.get('Todo-456')).toBeUndefined();
+    });
+
+    it('should create nodes with generated internal ID when using idField', async () => {
+      const customStore = new NodeStore();
+      const actions = createNodeActions({
+        store: customStore,
+        owner: 'test-plugin',
+      });
+
+      // Register index for idField
+      customStore.registerIndex('Product', 'externalId');
+
+      const lookupHandler = createDefaultWebhookHandler('test-plugin', {
+        idField: 'externalId',
+      });
+
+      const res = createMockResponse();
+      await lookupHandler(null as never, res, {
+        store: customStore,
+        actions,
+        rawBody: Buffer.from('{}'),
+        body: {
+          operation: 'create',
+          nodeId: '789', // External ID (string)
+          nodeType: 'Product',
+          data: { externalId: '789', name: 'New Product' },
+        },
+      });
+
+      expect(res.getStatusCode()).toBe(201);
+      const responseBody = JSON.parse(res.getBody());
+      expect(responseBody).toMatchObject({
+        created: true,
+        nodeId: '789',
+      });
+
+      // Internal ID is generated using createNodeId (SHA-256 hash)
+      expect(responseBody.internalId).toBeDefined();
+      expect(typeof responseBody.internalId).toBe('string');
+
+      // Node should exist with the generated internal ID
+      const node = customStore.get(responseBody.internalId);
+      expect(node).toBeDefined();
+      expect((node as Record<string, unknown>).name).toBe('New Product');
+    });
+
+    it('should find nodes when externalId is numeric but nodeId is string', async () => {
+      const customStore = new NodeStore();
+      const actions = createNodeActions({
+        store: customStore,
+        owner: 'test-plugin',
+      });
+
+      // Register index for idField
+      customStore.registerIndex('Todo', 'externalId');
+
+      // Pre-create a node with NUMERIC externalId (common in databases)
+      customStore.set({
+        internal: {
+          id: 'Todo-internal-123',
+          type: 'Todo',
+          owner: 'test-plugin',
+          contentDigest: 'abc',
+        },
+        externalId: 42, // Stored as NUMBER
+        title: 'Original Title',
+      });
+
+      const lookupHandler = createDefaultWebhookHandler('test-plugin', {
+        idField: 'externalId',
+      });
+
+      const res = createMockResponse();
+      await lookupHandler(null as never, res, {
+        store: customStore,
+        actions,
+        rawBody: Buffer.from('{}'),
+        body: {
+          operation: 'update',
+          nodeId: '42', // Sent as STRING (JSON always sends strings)
+          nodeType: 'Todo',
+          data: { externalId: 42, title: 'Updated Title' },
+        },
+      });
+
+      expect(res.getStatusCode()).toBe(200);
+      expect(JSON.parse(res.getBody())).toMatchObject({
+        updated: true,
+        nodeId: '42',
+        internalId: 'Todo-internal-123',
+      });
+
+      // Check that the node was updated
+      const node = customStore.get('Todo-internal-123');
+      expect((node as Record<string, unknown>).title).toBe('Updated Title');
+    });
+
+    it('should upsert existing nodes found by idField', async () => {
+      const customStore = new NodeStore();
+      const actions = createNodeActions({
+        store: customStore,
+        owner: 'test-plugin',
+      });
+
+      // Register index
+      customStore.registerIndex('Item', 'itemCode');
+
+      // Pre-create a node
+      customStore.set({
+        internal: {
+          id: 'Item-ABC',
+          type: 'Item',
+          owner: 'test-plugin',
+          contentDigest: 'orig',
+        },
+        itemCode: 'ABC',
+        value: 100,
+      });
+
+      const lookupHandler = createDefaultWebhookHandler('test-plugin', {
+        idField: 'itemCode',
+      });
+
+      const res = createMockResponse();
+      await lookupHandler(null as never, res, {
+        store: customStore,
+        actions,
+        rawBody: Buffer.from('{}'),
+        body: {
+          operation: 'upsert',
+          nodeId: 'ABC', // Using itemCode
+          nodeType: 'Item',
+          data: { itemCode: 'ABC', value: 200 },
+        },
+      });
+
+      expect(res.getStatusCode()).toBe(200);
+      expect(JSON.parse(res.getBody())).toMatchObject({
+        upserted: true,
+        nodeId: 'ABC',
+        internalId: 'Item-ABC',
+        wasUpdate: true,
+      });
+
+      // Check that the existing node was updated
+      const node = customStore.get('Item-ABC');
+      expect((node as Record<string, unknown>).value).toBe(200);
+    });
+  });
+});
diff --git a/packages/core/tests/unit/webhooks/register-default.test.ts b/packages/core/tests/unit/webhooks/register-default.test.ts
new file mode 100644
index 0000000..26aaf1f
--- /dev/null
+++ b/packages/core/tests/unit/webhooks/register-default.test.ts
@@ -0,0 +1,212 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { WebhookRegistry } from '@/webhooks/registry.js';
+import {
+  registerDefaultWebhook,
+  registerDefaultWebhooks,
+} from '@/webhooks/register-default.js';
+import type { DefaultWebhookHandlerConfig } from '@/webhooks/types.js';
+
+describe('registerDefaultWebhook', () => {
+  let registry: WebhookRegistry;
+  let consoleSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    registry = new WebhookRegistry();
+    consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+  });
+
+  it('should not register if config is undefined', () => {
+    const result = registerDefaultWebhook(registry, 'test-plugin', undefined);
+
+    expect(result).toBeNull();
+    expect(registry.size()).toBe(0);
+  });
+
+  it('should not register if enabled is false', () => {
+    const config: DefaultWebhookHandlerConfig = { enabled: false };
+    const result = registerDefaultWebhook(registry, 'test-plugin', config);
+
+    expect(result).toBeNull();
+    expect(registry.size()).toBe(0);
+  });
+
+  it('should register with default path "sync" when enabled', () => {
+    const config: DefaultWebhookHandlerConfig = { enabled: true };
+    const result = registerDefaultWebhook(registry, 'test-plugin', config);
+
+    expect(result).toBe('sync');
+    expect(registry.has('test-plugin', 'sync')).toBe(true);
+    expect(consoleSpy).toHaveBeenCalledWith(
+      '📬 Default webhook registered: /_webhooks/test-plugin/sync'
+    );
+  });
+
+  it('should register when config is empty object (enabled by default)', () => {
+    const config: DefaultWebhookHandlerConfig = {};
+    const result = registerDefaultWebhook(registry, 'test-plugin', config);
+
+    expect(result).toBe('sync');
+    expect(registry.has('test-plugin', 'sync')).toBe(true);
+  });
+
+  it('should use custom global path', () => {
+    const config: DefaultWebhookHandlerConfig = {
+      enabled: true,
+      path: 'custom-sync',
+    };
+    const result = registerDefaultWebhook(registry, 'test-plugin', config);
+
+    expect(result).toBe('custom-sync');
+    expect(registry.has('test-plugin', 'custom-sync')).toBe(true);
+  });
+
+  it('should use per-plugin path override', () => {
+    const config: DefaultWebhookHandlerConfig = {
+      enabled: true,
+      path: 'global-sync',
+      plugins: {
+        'test-plugin': { path: 'plugin-specific' },
+      },
+    };
+    const result = registerDefaultWebhook(registry, 'test-plugin', config);
+
+    expect(result).toBe('plugin-specific');
+    expect(registry.has('test-plugin', 'plugin-specific')).toBe(true);
+    expect(registry.has('test-plugin', 'global-sync')).toBe(false);
+  });
+
+  it('should use global path for plugins without override', () => {
+    const config: DefaultWebhookHandlerConfig = {
+      enabled: true,
+      path: 'global-sync',
+      plugins: {
+        'other-plugin': { path: 'other-path' },
+      },
+    };
+    const result = registerDefaultWebhook(registry, 'test-plugin', config);
+
+    expect(result).toBe('global-sync');
+    expect(registry.has('test-plugin', 'global-sync')).toBe(true);
+  });
+
+  it('should not register if plugin is explicitly disabled', () => {
+    const config: DefaultWebhookHandlerConfig = {
+      enabled: true,
+      plugins: {
+        'disabled-plugin': false,
+      },
+    };
+    const result = registerDefaultWebhook(registry, 'disabled-plugin', config);
+
+    expect(result).toBeNull();
+    expect(registry.size()).toBe(0);
+    expect(consoleSpy).toHaveBeenCalledWith(
+      '📭 Default webhook disabled for plugin: disabled-plugin'
+    );
+  });
+
+  it('should not overwrite existing handler', () => {
+    // Register a custom handler first
+    registry.register('test-plugin', {
+      path: 'sync',
+      handler: async () => {},
+      description: 'Custom handler',
+    });
+
+    const config: DefaultWebhookHandlerConfig = { enabled: true };
+    const result = registerDefaultWebhook(registry, 'test-plugin', config);
+
+    expect(result).toBeNull();
+    // Verify original handler is preserved
+    const handler = registry.getHandler('test-plugin', 'sync');
+    expect(handler?.description).toBe('Custom handler');
+    expect(consoleSpy).toHaveBeenCalledWith(
+      "📌 Plugin test-plugin already has handler for 'sync', skipping default registration"
+    );
+  });
+
+  it('should register handler with correct description', () => {
+    const config: DefaultWebhookHandlerConfig = { enabled: true };
+    registerDefaultWebhook(registry, 'my-plugin', config);
+
+    const handler = registry.getHandler('my-plugin', 'sync');
+    expect(handler?.description).toBe('Default UDL sync handler for my-plugin');
+  });
+});
+
+describe('registerDefaultWebhooks', () => {
+  let registry: WebhookRegistry;
+
+  beforeEach(() => {
+    registry = new WebhookRegistry();
+    vi.spyOn(console, 'log').mockImplementation(() => {});
+  });
+
+  it('should register for multiple plugins', () => {
+    const config: DefaultWebhookHandlerConfig = { enabled: true };
+    const plugins = ['plugin-a', 'plugin-b', 'plugin-c'];
+
+    const results = registerDefaultWebhooks(registry, plugins, config);
+
+    expect(results.size).toBe(3);
+    expect(results.get('plugin-a')).toBe('sync');
+    expect(results.get('plugin-b')).toBe('sync');
+    expect(results.get('plugin-c')).toBe('sync');
+    expect(registry.size()).toBe(3);
+  });
+
+  it('should handle mixed enable/disable per plugin', () => {
+    const config: DefaultWebhookHandlerConfig = {
+      enabled: true,
+      plugins: {
+        'plugin-b': false,
+      },
+    };
+    const plugins = ['plugin-a', 'plugin-b', 'plugin-c'];
+
+    const results = registerDefaultWebhooks(registry, plugins, config);
+
+    expect(results.get('plugin-a')).toBe('sync');
+    expect(results.get('plugin-b')).toBeNull();
+    expect(results.get('plugin-c')).toBe('sync');
+    expect(registry.size()).toBe(2);
+  });
+
+  it('should handle custom paths per plugin', () => {
+    const config: DefaultWebhookHandlerConfig = {
+      enabled: true,
+      path: 'default-path',
+      plugins: {
+        'plugin-a': { path: 'path-a' },
+        'plugin-c': { path: 'path-c' },
+      },
+    };
+    const plugins = ['plugin-a', 'plugin-b', 'plugin-c'];
+
+    const results = registerDefaultWebhooks(registry, plugins, config);
+
+    expect(results.get('plugin-a')).toBe('path-a');
+    expect(results.get('plugin-b')).toBe('default-path');
+    expect(results.get('plugin-c')).toBe('path-c');
+  });
+
+  it('should return empty results when config is undefined', () => {
+    const plugins = ['plugin-a', 'plugin-b'];
+
+    const results = registerDefaultWebhooks(registry, plugins, undefined);
+
+    expect(results.size).toBe(2);
+    expect(results.get('plugin-a')).toBeNull();
+    expect(results.get('plugin-b')).toBeNull();
+    expect(registry.size()).toBe(0);
+  });
+
+  it('should handle empty plugin list', () => {
+    const config: DefaultWebhookHandlerConfig = { enabled: true };
+
+    const results = registerDefaultWebhooks(registry, [], config);
+
+    expect(results.size).toBe(0);
+    expect(registry.size()).toBe(0);
+  });
+});

From 4c3b7646b2bd25047b0b9332876798e8dfc0b252 Mon Sep 17 00:00:00 2001
From: dawidurbanski <hi@dawidurbanski.com>
Date: Mon, 22 Dec 2025 17:04:06 +0100
Subject: [PATCH 16/46] feat(core): integrate default webhook into plugin
 loading

Integrate the default webhook handler system into the plugin loading process:

- Add `idField` config option for plugins to specify their external ID field
- Auto-register default webhook handlers for plugins when `defaultWebhook`
  config is enabled
- Automatically index the idField for O(1) lookups
- Update UDLConfig interface with defaultWebhook configuration
- Re-export default webhook types and functions from core package

When a plugin specifies an idField (e.g., 'contentfulId'), the default
webhook handler uses this field to look up existing nodes, enabling
external systems to reference nodes by their source IDs.
---
 packages/core/src/index.ts  |  8 +++++
 packages/core/src/loader.ts | 59 +++++++++++++++++++++++++++++++++++--
 2 files changed, 65 insertions(+), 2 deletions(-)

diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 739dfad..9e3b729 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -142,6 +142,14 @@ export {
   type WebhookHandlerFn,
   type WebhookHandlerContext,
   type WebhookHandler,
+  // Default webhook handler
+  type DefaultWebhookPayload,
+  type DefaultWebhookHandlerConfig,
+  type PluginDefaultWebhookConfig,
+  createDefaultWebhookHandler,
+  DEFAULT_WEBHOOK_PATH,
+  registerDefaultWebhook,
+  registerDefaultWebhooks,
 } from './webhooks/index.js';
 
 // Export the default server for programmatic usage
diff --git a/packages/core/src/loader.ts b/packages/core/src/loader.ts
index 189f6d5..05a35cf 100644
--- a/packages/core/src/loader.ts
+++ b/packages/core/src/loader.ts
@@ -15,9 +15,11 @@ import type {
 } from '@/references/types.js';
 import {
   defaultWebhookRegistry,
+  registerDefaultWebhook,
   type WebhookRegistry,
   type WebhookRegistration,
   type WebhookHooksConfig,
+  type DefaultWebhookHandlerConfig,
 } from '@/webhooks/index.js';
 
 export const pluginTypes = ['core', 'source', 'other'] as const;
@@ -183,7 +185,20 @@ export interface UDLConfig {
   staticPath?: string;
   /** List of plugins to load */
   plugins?: PluginSpec[];
-  /** Default indexed fields for this plugin (for source plugins) */
+  /**
+   * The unique identifier field for nodes from this source plugin.
+   * This field is used by the default webhook handler to look up existing nodes
+   * when processing update/delete operations from external systems.
+   *
+   * The idField is automatically indexed for O(1) lookups.
+   *
+   * @example 'externalId' - for generic external IDs
+   * @example 'contentfulId' - for Contentful entries
+   * @example 'shopifyId' - for Shopify resources
+   */
+  idField?: string;
+
+  /** Additional indexed fields for this plugin (for source plugins) */
   indexes?: string[];
   /** Code generation configuration - when set, automatically generates types after sourceNodes */
   codegen?: CodegenConfig;
@@ -198,6 +213,28 @@ export interface UDLConfig {
    * Configuration for remote data synchronization (webhooks, etc.).
    */
   remote?: RemoteConfig;
+  /**
+   * Configuration for automatic default webhook handlers.
+   * When enabled, registers a default 'sync' webhook endpoint for each loaded plugin
+   * that accepts standardized create/update/delete/upsert payloads.
+   *
+   * @example
+   * ```typescript
+   * defineConfig({
+   *   defaultWebhook: {
+   *     enabled: true,
+   *     path: 'sync', // Default endpoint path for all plugins
+   *     plugins: {
+   *       // Customize path for specific plugin
+   *       'contentful': { path: 'content-sync' },
+   *       // Disable for a specific plugin
+   *       'legacy-plugin': false,
+   *     },
+   *   },
+   * });
+   * ```
+   */
+  defaultWebhook?: DefaultWebhookHandlerConfig;
 }
 
 /**
@@ -657,11 +694,19 @@ export async function loadPlugins(
 
         // Execute sourceNodes hook and register indexes
         if (module.sourceNodes && nodeStore) {
+          // Get the idField from plugin config (used for webhook lookups)
+          const pluginIdField = module.config?.idField;
+
+          // Build indexes: idField is always indexed if specified
           const pluginDefaultIndexes = module.config?.indexes || [];
           const userIndexes =
             (pluginOptions as { indexes?: string[] })?.indexes || [];
           const allIndexes = [
-            ...new Set([...pluginDefaultIndexes, ...userIndexes]),
+            ...new Set([
+              ...(pluginIdField ? [pluginIdField] : []),
+              ...pluginDefaultIndexes,
+              ...userIndexes,
+            ]),
           ];
 
           // Determine if caching is enabled for this plugin
@@ -722,6 +767,16 @@ export async function loadPlugins(
 
           registerPluginIndexes(nodeStore, actualPluginName, allIndexes);
 
+          // Register default webhook handler if enabled in config
+          if (appConfig?.defaultWebhook) {
+            registerDefaultWebhook(
+              webhookRegistry,
+              actualPluginName,
+              appConfig.defaultWebhook,
+              pluginIdField
+            );
+          }
+
           // Save plugin's nodes after sourceNodes
           if (shouldCache && pluginCache) {
             // Get only nodes owned by this plugin

From cb15ef583aaa672076c3b4afab800d2657ab66d1 Mon Sep 17 00:00:00 2001
From: dawidurbanski <hi@dawidurbanski.com>
Date: Mon, 22 Dec 2025 17:04:21 +0100
Subject: [PATCH 17/46] chore(core): add remote-todo MSW mock for webhook
 manual testing

Add MSW mock handlers for testing the default webhook functionality
with a remote todo API simulation. Includes manual test feature for
verifying webhook-based CRUD operations in development mode.
---
 packages/core/src/mocks/index.ts              |  25 +-
 .../remote-udl-webhooks/description.md        | 239 +++++++
 .../features/remote-udl-webhooks/index.tsx    | 666 ++++++++++++++++++
 .../features/remote-udl-webhooks/manifest.ts  |  12 +
 .../remote-udl-webhooks/mocks/remote-todos.ts | 228 ++++++
 .../plugins/remote-todo-source/udl.config.ts  |  75 ++
 .../remote-udl-webhooks/udl.config.ts         |  26 +
 7 files changed, 1270 insertions(+), 1 deletion(-)
 create mode 100644 packages/core/tests/manual/features/remote-udl-webhooks/description.md
 create mode 100644 packages/core/tests/manual/features/remote-udl-webhooks/index.tsx
 create mode 100644 packages/core/tests/manual/features/remote-udl-webhooks/manifest.ts
 create mode 100644 packages/core/tests/manual/features/remote-udl-webhooks/mocks/remote-todos.ts
 create mode 100644 packages/core/tests/manual/features/remote-udl-webhooks/plugins/remote-todo-source/udl.config.ts
 create mode 100644 packages/core/tests/manual/features/remote-udl-webhooks/udl.config.ts

diff --git a/packages/core/src/mocks/index.ts b/packages/core/src/mocks/index.ts
index eb1a9ec..22561e9 100644
--- a/packages/core/src/mocks/index.ts
+++ b/packages/core/src/mocks/index.ts
@@ -15,6 +15,24 @@ async function loadContentfulHandlers(): Promise<RequestHandler[]> {
   }
 }
 
+// Load remote-todo handlers for the manual test feature
+// Uses string concatenation to prevent TypeScript from resolving at compile time
+async function loadRemoteTodoHandlers(): Promise<RequestHandler[]> {
+  try {
+    // Only load in development mode for manual testing
+    if (process.env['NODE_ENV'] !== 'development') return [];
+
+    const modulePath =
+      '../../tests/manual/features/remote-udl-webhooks/mocks/' +
+      'remote-todos.js';
+    const mod = await import(/* webpackIgnore: true */ modulePath);
+    return mod.remoteTodoHandlers || [];
+  } catch {
+    // Feature not available or handlers not found
+    return [];
+  }
+}
+
 /**
  * Check if real Contentful credentials are provided
  */
@@ -100,8 +118,13 @@ export async function startMockServer() {
   }
 
   const contentfulHandlers = await loadContentfulHandlers();
+  const remoteTodoHandlers = await loadRemoteTodoHandlers();
 
-  mockServer = setupServer(...contentfulHandlers, ...jsonplaceholderHandlers);
+  mockServer = setupServer(
+    ...contentfulHandlers,
+    ...jsonplaceholderHandlers,
+    ...remoteTodoHandlers
+  );
 
   mockServer.listen({ onUnhandledRequest: 'bypass' });
   console.log(`🔶 MSW Mock Server started (${reason})`);
diff --git a/packages/core/tests/manual/features/remote-udl-webhooks/description.md b/packages/core/tests/manual/features/remote-udl-webhooks/description.md
new file mode 100644
index 0000000..b9aa137
--- /dev/null
+++ b/packages/core/tests/manual/features/remote-udl-webhooks/description.md
@@ -0,0 +1,239 @@
+# Remote UDL with Webhooks Demo
+
+This manual test demonstrates the **remote UDL pattern** where data syncs from an external system via webhooks, without needing an actual remote UDL server.
+
+**Note:** The "Remote" store persists to localStorage, so changes survive page refreshes. The webhook log is also persisted.
+
+## What This Tests
+
+1. **MSW Mocking** - REST API calls intercepted by Mock Service Worker
+2. **Webhook Integration** - MSW handlers send webhooks to UDL after mutations
+3. **Default Webhook Handler** - UDL's built-in handler processes CRUD webhooks
+4. **Real-time Sync** - Data changes propagate from "remote" to UDL
+
+## Architecture
+
+```
+┌─────────────────────┐     ┌─────────────────────┐     ┌─────────────────────┐
+│   React UI          │────▶│   MSW Handlers      │────▶│   UDL Server        │
+│   (Browser)         │     │   (Mock Backend)    │     │   (localhost:4000)  │
+│                     │◀────│                     │     │                     │
+│  • Todo list        │     │  • Intercept REST   │     │  • Receives webhooks│
+│  • Add/Edit/Delete  │     │  • In-memory store  │     │  • Updates nodes    │
+│  • Query UDL        │     │  • Send webhooks    │     │  • GraphQL queries  │
+└─────────────────────┘     └─────────────────────┘     └─────────────────────┘
+```
+
+## Data Flow
+
+### Initial Load
+
+```
+Plugin sourceNodes
+    ↓ fetch
+MSW: GET http://localhost:3001/api/todos
+    ↓ mock response
+Plugin creates RemoteTodo nodes in UDL
+    ↓
+GraphQL schema built
+    ↓
+UI queries UDL
+```
+
+### CRUD Operations
+
+```
+User clicks "Add Todo"
+    ↓ POST
+MSW: POST http://localhost:3001/api/todos
+    ↓
+MSW updates in-memory store
+MSW sends webhook to UDL
+    ↓ POST /_webhooks/remote-todo-source/sync
+UDL default handler creates node
+    ↓
+User clicks "Refresh from UDL"
+    ↓ GraphQL query
+UI shows updated data
+```
+
+## Webhook Payload Format
+
+The MSW handlers send webhooks using UDL's default webhook format:
+
+```json
+{
+  "operation": "create",
+  "nodeId": "RemoteTodo-4",
+  "nodeType": "RemoteTodo",
+  "data": {
+    "todoId": 4,
+    "title": "New todo item",
+    "completed": false
+  }
+}
+```
+
+### Supported Operations
+
+| Operation | Description          | Response                    |
+| --------- | -------------------- | --------------------------- |
+| `create`  | Create new node      | 201 Created (409 if exists) |
+| `update`  | Update existing node | 200 OK (404 if not found)   |
+| `delete`  | Delete node          | 200 OK (404 if not found)   |
+| `upsert`  | Create or update     | 200 OK (always succeeds)    |
+
+## Important: Node ID Format
+
+The plugin uses a **predictable ID format** (`RemoteTodo-{id}`) instead of the default
+`createNodeId()` function (which generates SHA-256 hashes). This allows the browser
+to replicate the same IDs when sending webhooks, ensuring updates go to the correct nodes.
+
+```typescript
+// Plugin uses simple format:
+const nodeId = `RemoteTodo-${todo.id}`; // "RemoteTodo-1"
+
+// NOT the default createNodeId:
+// createNodeId('RemoteTodo', '1') → "49fdbcb26d..."  (SHA-256 hash)
+```
+
+## Plugin Configuration
+
+### Remote Todo Source (`plugins/remote-todo-source/udl.config.ts`)
+
+```typescript
+export async function sourceNodes({
+  actions,
+  createNodeId,
+  createContentDigest,
+}) {
+  // Fetch from MSW-mocked endpoint
+  const response = await fetch('http://localhost:3001/api/todos');
+  const todos = await response.json();
+
+  for (const todo of todos) {
+    await actions.createNode({
+      internal: {
+        id: createNodeId('RemoteTodo', String(todo.id)),
+        type: 'RemoteTodo',
+        owner: 'remote-todo-source',
+        contentDigest: createContentDigest(todo),
+      },
+      todoId: todo.id,
+      title: todo.title,
+      completed: todo.completed,
+    });
+  }
+}
+```
+
+### Feature Config (`udl.config.ts`)
+
+```typescript
+export const config = defineConfig({
+  plugins: [{ name: './plugins/remote-todo-source', options: {} }],
+  // Enable default webhook handler
+  defaultWebhook: {
+    enabled: true,
+    path: 'sync', // Endpoint: /_webhooks/remote-todo-source/sync
+  },
+});
+```
+
+## MSW Handlers
+
+The MSW handlers in `mocks/remote-todos.ts` intercept REST calls and send webhooks:
+
+```typescript
+http.post('http://localhost:3001/api/todos', async ({ request }) => {
+  const body = await request.json();
+  const newTodo = { id: nextId++, ...body };
+  todos.push(newTodo);
+
+  // Send webhook to UDL
+  await fetch('http://localhost:4000/_webhooks/remote-todo-source/sync', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      operation: 'create',
+      nodeId: `RemoteTodo-${newTodo.id}`,
+      nodeType: 'RemoteTodo',
+      data: {
+        todoId: newTodo.id,
+        title: newTodo.title,
+        completed: newTodo.completed,
+      },
+    }),
+  });
+
+  return HttpResponse.json(newTodo, { status: 201 });
+});
+```
+
+## Key Concepts
+
+### Why MSW?
+
+MSW (Mock Service Worker) intercepts HTTP requests at the network level:
+
+- Works with any HTTP client (fetch, axios, etc.)
+- Handlers run in Node.js (same process as UDL server)
+- `onUnhandledRequest: 'bypass'` allows webhook requests to reach UDL
+
+### Why Manual Refresh?
+
+This demo uses manual refresh to clearly demonstrate:
+
+1. CRUD operation happens (REST call)
+2. Webhook is sent to UDL
+3. User explicitly refreshes to see changes
+
+In production, you might use:
+
+- Automatic refresh after webhook debounce
+- WebSocket for real-time updates
+- Polling at intervals
+
+### Reset Remote Store Button
+
+The "Reset Remote Store" button:
+
+1. Resets the Remote store to initial 3 items
+2. Calculates what changed (deleted items, added items, modified items)
+3. Sends reconciliation webhooks to UDL to sync:
+   - CREATE webhooks for items that need to be restored
+   - DELETE webhooks for items that were added and need removal
+   - UPDATE webhooks for items that were modified
+4. Clears the webhook log
+
+This ensures UDL always mirrors the Remote store state.
+
+### Default Webhook Handler
+
+UDL's default webhook handler provides:
+
+- Standardized CRUD operations
+- Automatic node management
+- No custom handler code needed
+
+Enable in config:
+
+```typescript
+defaultWebhook: {
+  enabled: true,
+  path: 'sync',
+}
+```
+
+## Testing Steps
+
+1. Start the UDL server (`npm run dev` in packages/core)
+2. Open the manual test harness
+3. Navigate to "Remote UDL with Webhooks"
+4. Initial todos should load automatically
+5. Add a new todo using the form
+6. Click "Refresh from UDL" to see the new todo
+7. Toggle a todo's completion status
+8. Click "Refresh from UDL" to see the change
+9. Delete a todo
+10. Click "Refresh from UDL" to verify deletion
diff --git a/packages/core/tests/manual/features/remote-udl-webhooks/index.tsx b/packages/core/tests/manual/features/remote-udl-webhooks/index.tsx
new file mode 100644
index 0000000..f2d6557
--- /dev/null
+++ b/packages/core/tests/manual/features/remote-udl-webhooks/index.tsx
@@ -0,0 +1,666 @@
+/**
+ * Remote UDL with Webhooks - Manual Test UI
+ *
+ * This component demonstrates the remote UDL pattern:
+ * 1. CRUD operations are handled in an in-memory "remote" store (simulating a backend)
+ * 2. After each mutation, a webhook is sent to UDL
+ * 3. User clicks "Refresh from UDL" to see the synced data
+ *
+ * Note: The "remote" store is in-memory in the browser. In a real scenario,
+ * this would be a separate backend service sending webhooks.
+ */
+
+import { useState, useEffect, useRef } from 'react';
+import { udl, gql } from 'universal-data-layer/client';
+
+interface Todo {
+  id: number;
+  title: string;
+  completed: boolean;
+}
+
+interface RemoteTodo {
+  todoId: number;
+  title: string;
+  completed: boolean;
+  internal: {
+    id: string;
+    type: string;
+    owner: string;
+    contentDigest: string;
+  };
+}
+
+// UDL server webhook endpoint
+const UDL_WEBHOOK_URL =
+  'http://localhost:4000/_webhooks/remote-todo-source/sync';
+
+// Initial seed data (matches what sourceNodes loads)
+const initialTodos: Todo[] = [
+  { id: 1, title: 'Learn UDL', completed: false },
+  { id: 2, title: 'Build awesome apps', completed: false },
+  { id: 3, title: 'Test webhooks', completed: true },
+];
+
+// localStorage keys
+const STORAGE_KEY_TODOS = 'udl-remote-webhooks-todos';
+const STORAGE_KEY_NEXT_ID = 'udl-remote-webhooks-next-id';
+const STORAGE_KEY_WEBHOOK_LOG = 'udl-remote-webhooks-log';
+
+// Load persisted data from localStorage
+function loadPersistedTodos(): Todo[] {
+  try {
+    const stored = localStorage.getItem(STORAGE_KEY_TODOS);
+    if (stored) {
+      return JSON.parse(stored);
+    }
+  } catch (e) {
+    console.error('[RemoteUDL] Failed to load todos from localStorage:', e);
+  }
+  return [...initialTodos];
+}
+
+function loadPersistedNextId(): number {
+  try {
+    const stored = localStorage.getItem(STORAGE_KEY_NEXT_ID);
+    if (stored) {
+      return parseInt(stored, 10);
+    }
+  } catch (e) {
+    console.error('[RemoteUDL] Failed to load nextId from localStorage:', e);
+  }
+  return 4;
+}
+
+function loadPersistedWebhookLog(): string[] {
+  try {
+    const stored = localStorage.getItem(STORAGE_KEY_WEBHOOK_LOG);
+    if (stored) {
+      return JSON.parse(stored);
+    }
+  } catch (e) {
+    console.error(
+      '[RemoteUDL] Failed to load webhook log from localStorage:',
+      e
+    );
+  }
+  return [];
+}
+
+/**
+ * Generate node ID matching the plugin's createNodeId pattern.
+ */
+function createNodeId(type: string, id: string): string {
+  return `${type}-${id}`;
+}
+
+export default function RemoteUDLWebhooks() {
+  // "Remote" store - persisted to localStorage (simulates backend)
+  const [remoteTodos, setRemoteTodos] = useState<Todo[]>(loadPersistedTodos);
+  const remoteTodosRef = useRef(remoteTodos);
+  remoteTodosRef.current = remoteTodos; // Keep ref in sync
+  const nextIdRef = useRef(loadPersistedNextId());
+
+  // UDL data (fetched via GraphQL)
+  const [udlTodos, setUdlTodos] = useState<RemoteTodo[]>([]);
+
+  // UI state
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string>('');
+  const [newTodoTitle, setNewTodoTitle] = useState('');
+  const [lastAction, setLastAction] = useState<string>('');
+  const [webhookLog, setWebhookLog] = useState<string[]>(
+    loadPersistedWebhookLog
+  );
+
+  // Persist remoteTodos to localStorage whenever it changes
+  useEffect(() => {
+    localStorage.setItem(STORAGE_KEY_TODOS, JSON.stringify(remoteTodos));
+    localStorage.setItem(STORAGE_KEY_NEXT_ID, String(nextIdRef.current));
+  }, [remoteTodos]);
+
+  // Persist webhookLog to localStorage whenever it changes
+  useEffect(() => {
+    localStorage.setItem(STORAGE_KEY_WEBHOOK_LOG, JSON.stringify(webhookLog));
+  }, [webhookLog]);
+
+  // Add to webhook log
+  const logWebhook = (message: string) => {
+    const timestamp = new Date().toLocaleTimeString();
+    setWebhookLog((prev) => [`[${timestamp}] ${message}`, ...prev.slice(0, 9)]);
+  };
+
+  /**
+   * Send a webhook to UDL to notify about data changes.
+   */
+  const sendWebhook = async (
+    operation: 'create' | 'update' | 'delete' | 'upsert',
+    nodeId: string,
+    nodeType: string,
+    data?: Record<string, unknown>
+  ): Promise<boolean> => {
+    try {
+      const response = await fetch(UDL_WEBHOOK_URL, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          operation,
+          nodeId,
+          nodeType,
+          data,
+        }),
+      });
+
+      if (!response.ok) {
+        console.error(
+          `Webhook failed: ${response.status} ${response.statusText}`
+        );
+        logWebhook(`FAILED: ${operation} ${nodeId} - ${response.status}`);
+        return false;
+      }
+
+      logWebhook(`${operation.toUpperCase()} ${nodeId} -> OK`);
+      return true;
+    } catch (err) {
+      console.error('Failed to send webhook:', err);
+      logWebhook(`FAILED: ${operation} ${nodeId} - ${err}`);
+      return false;
+    }
+  };
+
+  // Fetch todos from UDL via GraphQL
+  const fetchFromUDL = async () => {
+    setLoading(true);
+    setError('');
+
+    try {
+      const [err, data] = await udl.query<RemoteTodo[]>(gql`
+        {
+          allRemoteTodos {
+            todoId
+            title
+            completed
+            internal {
+              id
+              type
+              owner
+              contentDigest
+            }
+          }
+        }
+      `);
+
+      if (err) throw new Error(err.message);
+      setUdlTodos(data || []);
+      setLastAction(`Refreshed from UDL - found ${data?.length || 0} todos`);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : 'Failed to fetch from UDL');
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  // Initial load
+  useEffect(() => {
+    fetchFromUDL();
+  }, []);
+
+  // Create new todo
+  const createTodo = async () => {
+    if (!newTodoTitle.trim()) return;
+
+    setError('');
+
+    const newTodo: Todo = {
+      id: nextIdRef.current++,
+      title: newTodoTitle,
+      completed: false,
+    };
+
+    // Update "remote" store immediately
+    setRemoteTodos((prev) => [...prev, newTodo]);
+    setNewTodoTitle('');
+
+    // Send webhook to UDL
+    const nodeId = createNodeId('RemoteTodo', String(newTodo.id));
+    const success = await sendWebhook('create', nodeId, 'RemoteTodo', {
+      todoId: newTodo.id,
+      title: newTodo.title,
+      completed: newTodo.completed,
+    });
+
+    if (success) {
+      setLastAction(`Created todo #${newTodo.id}: "${newTodo.title}"`);
+    } else {
+      setError('Failed to send webhook to UDL');
+    }
+  };
+
+  // Toggle todo completed
+  const toggleTodo = async (todoId: number) => {
+    setError('');
+
+    // Find todo from current state using ref (avoids stale closure)
+    const currentTodo = remoteTodosRef.current.find((t) => t.id === todoId);
+    if (!currentTodo) {
+      setError('Todo not found');
+      return;
+    }
+
+    const newCompleted = !currentTodo.completed;
+
+    // Update local state
+    setRemoteTodos((prev) =>
+      prev.map((t) => (t.id === todoId ? { ...t, completed: newCompleted } : t))
+    );
+
+    // Send webhook to UDL
+    const nodeId = createNodeId('RemoteTodo', String(todoId));
+    const success = await sendWebhook('upsert', nodeId, 'RemoteTodo', {
+      todoId: todoId,
+      title: currentTodo.title,
+      completed: newCompleted,
+    });
+
+    if (success) {
+      setLastAction(
+        `Toggled todo #${todoId} to ${newCompleted ? 'completed' : 'incomplete'}`
+      );
+    } else {
+      setError('Failed to send webhook to UDL');
+    }
+  };
+
+  // Delete todo
+  const deleteTodo = async (todoId: number) => {
+    setError('');
+
+    // Update "remote" store immediately
+    setRemoteTodos((prev) => prev.filter((t) => t.id !== todoId));
+
+    // Send webhook to UDL
+    const nodeId = createNodeId('RemoteTodo', String(todoId));
+    const success = await sendWebhook('delete', nodeId, 'RemoteTodo');
+
+    if (success) {
+      setLastAction(`Deleted todo #${todoId}`);
+    } else {
+      setError('Failed to send webhook to UDL');
+    }
+  };
+
+  // Reset to initial state and sync UDL via webhooks
+  const resetData = async () => {
+    setError('');
+
+    // Get current remote state before reset
+    const currentTodos = remoteTodosRef.current;
+    const currentIds = new Set(currentTodos.map((t) => t.id));
+    const initialIds = new Set(initialTodos.map((t) => t.id));
+
+    // Calculate what webhooks need to be sent to reconcile UDL with initial state
+    const webhooksToSend: Array<{
+      operation: 'create' | 'delete' | 'upsert';
+      nodeId: string;
+      nodeType: string;
+      data?: Record<string, unknown>;
+    }> = [];
+
+    // 1. Items in initial but not in current → need to CREATE in UDL
+    for (const todo of initialTodos) {
+      if (!currentIds.has(todo.id)) {
+        webhooksToSend.push({
+          operation: 'create',
+          nodeId: createNodeId('RemoteTodo', String(todo.id)),
+          nodeType: 'RemoteTodo',
+          data: {
+            todoId: todo.id,
+            title: todo.title,
+            completed: todo.completed,
+          },
+        });
+      }
+    }
+
+    // 2. Items in current but not in initial → need to DELETE from UDL
+    for (const todo of currentTodos) {
+      if (!initialIds.has(todo.id)) {
+        webhooksToSend.push({
+          operation: 'delete',
+          nodeId: createNodeId('RemoteTodo', String(todo.id)),
+          nodeType: 'RemoteTodo',
+        });
+      }
+    }
+
+    // 3. Items in both but with different values → need to UPDATE in UDL
+    for (const initialTodo of initialTodos) {
+      const currentTodo = currentTodos.find((t) => t.id === initialTodo.id);
+      if (currentTodo) {
+        // Check if values differ
+        if (
+          currentTodo.title !== initialTodo.title ||
+          currentTodo.completed !== initialTodo.completed
+        ) {
+          webhooksToSend.push({
+            operation: 'upsert',
+            nodeId: createNodeId('RemoteTodo', String(initialTodo.id)),
+            nodeType: 'RemoteTodo',
+            data: {
+              todoId: initialTodo.id,
+              title: initialTodo.title,
+              completed: initialTodo.completed,
+            },
+          });
+        }
+      }
+    }
+
+    // Reset remote store to initial state
+    setRemoteTodos([...initialTodos]);
+    nextIdRef.current = 4;
+
+    // Send all reconciliation webhooks and collect log entries
+    if (webhooksToSend.length === 0) {
+      setWebhookLog([]);
+      setLastAction(
+        'Reset complete - no webhooks needed (state already matches initial)'
+      );
+    } else {
+      const newLogEntries: string[] = [];
+      let successCount = 0;
+
+      for (const webhook of webhooksToSend) {
+        try {
+          const response = await fetch(UDL_WEBHOOK_URL, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+              operation: webhook.operation,
+              nodeId: webhook.nodeId,
+              nodeType: webhook.nodeType,
+              data: webhook.data,
+            }),
+          });
+
+          const timestamp = new Date().toLocaleTimeString();
+          if (response.ok) {
+            successCount++;
+            newLogEntries.push(
+              `[${timestamp}] ${webhook.operation.toUpperCase()} ${webhook.nodeId} -> OK`
+            );
+          } else {
+            newLogEntries.push(
+              `[${timestamp}] FAILED: ${webhook.operation} ${webhook.nodeId} - ${response.status}`
+            );
+          }
+        } catch (err) {
+          const timestamp = new Date().toLocaleTimeString();
+          newLogEntries.push(
+            `[${timestamp}] FAILED: ${webhook.operation} ${webhook.nodeId} - ${err}`
+          );
+        }
+      }
+
+      // Set all log entries at once (replacing old log)
+      setWebhookLog(newLogEntries);
+      setLastAction(
+        `Reset complete - sent ${successCount}/${webhooksToSend.length} reconciliation webhooks to UDL`
+      );
+    }
+  };
+
+  return (
+    <div className="max-w-5xl">
+      <div className="space-y-6">
+        {/* Architecture Info */}
+        <div className="bg-blue-50 border border-blue-200 rounded-lg p-4">
+          <h4 className="font-semibold text-blue-900 mb-2">
+            Architecture: Remote UDL with Webhooks
+          </h4>
+          <div className="text-sm text-blue-700 space-y-2">
+            <p>
+              <strong>Flow:</strong>
+            </p>
+            <ol className="list-decimal list-inside ml-4 space-y-1">
+              <li>
+                CRUD action updates the &quot;remote&quot; in-memory store
+                (simulates backend)
+              </li>
+              <li>
+                Webhook is sent to UDL:{' '}
+                <code className="bg-blue-100 px-1 rounded">
+                  POST /_webhooks/remote-todo-source/sync
+                </code>
+              </li>
+              <li>UDL default handler updates node store</li>
+              <li>
+                Click <strong>&quot;Refresh from UDL&quot;</strong> to see
+                updated data
+              </li>
+            </ol>
+          </div>
+        </div>
+
+        {/* Action Buttons */}
+        <div className="bg-gray-50 border border-gray-200 rounded-lg p-4">
+          <div className="flex flex-wrap gap-4 items-end">
+            <button
+              onClick={fetchFromUDL}
+              disabled={loading}
+              className="px-6 py-2 bg-green-600 text-white rounded-lg hover:bg-green-700 disabled:bg-gray-400 font-medium"
+            >
+              {loading ? 'Loading...' : 'Refresh from UDL'}
+            </button>
+
+            <button
+              onClick={resetData}
+              className="px-4 py-2 bg-gray-600 text-white rounded-lg hover:bg-gray-700"
+            >
+              Reset Remote Store
+            </button>
+
+            <span className="text-sm text-gray-500">
+              UDL Server: <code>http://localhost:4000</code>
+            </span>
+
+            <span
+              className={`text-sm px-2 py-1 rounded ${loading ? 'bg-yellow-200 text-yellow-800' : 'bg-green-200 text-green-800'}`}
+            >
+              {loading ? 'Loading...' : 'Ready'}
+            </span>
+          </div>
+        </div>
+
+        {/* Create Todo Form */}
+        <div className="bg-white border border-gray-200 rounded-lg p-4">
+          <h4 className="font-semibold text-gray-900 mb-3">Create New Todo</h4>
+          <div className="flex gap-2">
+            <input
+              type="text"
+              value={newTodoTitle}
+              onChange={(e) => setNewTodoTitle(e.target.value)}
+              placeholder="Enter todo title..."
+              className="flex-1 px-3 py-2 border border-gray-300 rounded-md focus:outline-none focus:ring-2 focus:ring-blue-500"
+              onKeyDown={(e) => e.key === 'Enter' && createTodo()}
+            />
+            <button
+              onClick={createTodo}
+              disabled={!newTodoTitle.trim()}
+              className="px-4 py-2 bg-blue-600 text-white rounded-lg hover:bg-blue-700 disabled:bg-gray-400"
+            >
+              Add Todo
+            </button>
+          </div>
+        </div>
+
+        {/* Status Messages */}
+        <div className="grid md:grid-cols-2 gap-4">
+          {/* Last Action - always visible */}
+          <div className="bg-yellow-50 border border-yellow-200 rounded-lg p-3">
+            <p className="text-sm text-yellow-800">
+              <strong>Last Action:</strong> {lastAction || 'None yet'}
+            </p>
+            <p className="text-xs text-yellow-600 mt-1">
+              Actions update this message to confirm they executed
+            </p>
+          </div>
+
+          {/* Webhook Log */}
+          {webhookLog.length > 0 && (
+            <div className="bg-purple-50 border border-purple-200 rounded-lg p-3">
+              <p className="text-sm font-semibold text-purple-900 mb-1">
+                Webhook Log:
+              </p>
+              <div className="text-xs text-purple-700 font-mono space-y-0.5 max-h-24 overflow-y-auto">
+                {webhookLog.map((log, i) => (
+                  <div key={i}>{log}</div>
+                ))}
+              </div>
+            </div>
+          )}
+        </div>
+
+        {/* Error Display */}
+        {error && (
+          <div className="bg-red-50 border border-red-200 rounded-lg p-4">
+            <p className="text-red-700">{error}</p>
+            <p className="text-sm text-red-600 mt-1">
+              Make sure the UDL server is running on port 4000
+            </p>
+          </div>
+        )}
+
+        {/* Side-by-side comparison */}
+        <div className="grid md:grid-cols-2 gap-6">
+          {/* Remote Store */}
+          <div className="bg-orange-50 border border-orange-200 rounded-lg p-4">
+            <h4 className="text-lg font-semibold text-orange-900 mb-4">
+              &quot;Remote&quot; Store ({remoteTodos.length} todos)
+            </h4>
+            <p className="text-xs text-orange-700 mb-3">
+              In-memory store simulating a backend. Changes here trigger
+              webhooks to UDL.
+            </p>
+            <div className="space-y-2">
+              {remoteTodos.map((todo) => (
+                <div
+                  key={todo.id}
+                  className={`border rounded p-3 ${
+                    todo.completed
+                      ? 'bg-green-50 border-green-200'
+                      : 'bg-white border-gray-200'
+                  }`}
+                >
+                  <div className="flex items-center justify-between">
+                    <div className="flex items-center gap-2">
+                      <input
+                        type="checkbox"
+                        checked={todo.completed}
+                        onChange={() => toggleTodo(todo.id)}
+                        className="w-4 h-4 cursor-pointer accent-green-600"
+                      />
+                      <span
+                        className={
+                          todo.completed ? 'line-through text-gray-500' : ''
+                        }
+                      >
+                        {todo.title}
+                      </span>
+                    </div>
+                    <div className="flex items-center gap-2">
+                      <span className="text-xs text-gray-500">#{todo.id}</span>
+                      <button
+                        onClick={() => deleteTodo(todo.id)}
+                        className="px-2 py-1 text-red-600 hover:bg-red-100 rounded text-xs"
+                      >
+                        Delete
+                      </button>
+                    </div>
+                  </div>
+                </div>
+              ))}
+            </div>
+          </div>
+
+          {/* UDL Store */}
+          <div className="bg-blue-50 border border-blue-200 rounded-lg p-4">
+            <h4 className="text-lg font-semibold text-blue-900 mb-4">
+              UDL Store ({udlTodos.length} todos)
+            </h4>
+            <p className="text-xs text-blue-700 mb-3">
+              Data from UDL via GraphQL. Click &quot;Refresh from UDL&quot; to
+              update.
+            </p>
+            {udlTodos.length === 0 ? (
+              <p className="text-gray-500 text-sm">
+                No todos found. Click &quot;Refresh from UDL&quot;.
+              </p>
+            ) : (
+              <div className="space-y-2">
+                {udlTodos.map((todo) => (
+                  <div
+                    key={todo.internal.id}
+                    className={`border rounded p-3 ${
+                      todo.completed
+                        ? 'bg-green-50 border-green-200'
+                        : 'bg-white border-gray-200'
+                    }`}
+                  >
+                    <div className="flex items-center justify-between">
+                      <div className="flex items-center gap-2">
+                        <input
+                          type="checkbox"
+                          checked={todo.completed}
+                          disabled
+                          className="w-4 h-4"
+                        />
+                        <span
+                          className={
+                            todo.completed ? 'line-through text-gray-500' : ''
+                          }
+                        >
+                          {todo.title}
+                        </span>
+                      </div>
+                      <span className="text-xs text-gray-500">
+                        #{todo.todoId}
+                      </span>
+                    </div>
+                    <p className="text-xs text-gray-400 mt-1 font-mono">
+                      {todo.internal.id}
+                    </p>
+                  </div>
+                ))}
+              </div>
+            )}
+          </div>
+        </div>
+
+        {/* Technical Details */}
+        <div className="bg-purple-50 border border-purple-200 rounded-lg p-4">
+          <h4 className="font-semibold text-purple-900 mb-2">
+            Webhook Payload Format
+          </h4>
+          <div className="text-sm text-purple-700">
+            <pre className="bg-white rounded p-3 text-xs overflow-x-auto border border-purple-200">
+              {`POST /_webhooks/remote-todo-source/sync
+Content-Type: application/json
+
+{
+  "operation": "create" | "update" | "delete" | "upsert",
+  "nodeId": "RemoteTodo-1",
+  "nodeType": "RemoteTodo",
+  "data": {
+    "todoId": 1,
+    "title": "Example todo",
+    "completed": false
+  }
+}`}
+            </pre>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/packages/core/tests/manual/features/remote-udl-webhooks/manifest.ts b/packages/core/tests/manual/features/remote-udl-webhooks/manifest.ts
new file mode 100644
index 0000000..ec5db0c
--- /dev/null
+++ b/packages/core/tests/manual/features/remote-udl-webhooks/manifest.ts
@@ -0,0 +1,12 @@
+import type { ScenarioManifest } from '../../../../../../tests/manual/src/types';
+
+const manifest: ScenarioManifest = {
+  package: 'core',
+  feature: 'remote-udl-webhooks',
+  title: 'Remote UDL with Webhooks',
+  description:
+    'Demonstrates CRUD operations with MSW-mocked REST API and UDL webhook integration for real-time sync',
+  dependsOn: [],
+};
+
+export default manifest;
diff --git a/packages/core/tests/manual/features/remote-udl-webhooks/mocks/remote-todos.ts b/packages/core/tests/manual/features/remote-udl-webhooks/mocks/remote-todos.ts
new file mode 100644
index 0000000..caca112
--- /dev/null
+++ b/packages/core/tests/manual/features/remote-udl-webhooks/mocks/remote-todos.ts
@@ -0,0 +1,228 @@
+/**
+ * MSW Handlers for Remote Todo API
+ *
+ * These handlers simulate a remote REST API that:
+ * 1. Stores todos in-memory
+ * 2. Sends webhooks to UDL after each mutation
+ *
+ * The webhooks allow UDL to stay in sync with the "remote" data source.
+ */
+
+import { http, HttpResponse } from 'msw';
+
+// Simple todo model
+interface Todo {
+  id: number;
+  title: string;
+  completed: boolean;
+}
+
+// Initial seed data - matches what sourceNodes will fetch
+const initialTodos: Todo[] = [
+  { id: 1, title: 'Learn UDL', completed: false },
+  { id: 2, title: 'Build awesome apps', completed: false },
+  { id: 3, title: 'Test webhooks', completed: true },
+];
+
+// Mutable in-memory store
+let todos: Todo[] = [...initialTodos];
+let nextId = 4;
+
+// UDL server webhook endpoint
+// MSW's onUnhandledRequest: 'bypass' allows this to reach the actual server
+const UDL_WEBHOOK_URL =
+  'http://localhost:4000/_webhooks/remote-todo-source/sync';
+
+/**
+ * Send a webhook to UDL to notify about data changes.
+ * Uses the default webhook payload format.
+ */
+async function sendWebhook(
+  operation: 'create' | 'update' | 'delete' | 'upsert',
+  nodeId: string,
+  nodeType: string,
+  data?: Record<string, unknown>
+): Promise<void> {
+  try {
+    const response = await fetch(UDL_WEBHOOK_URL, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        operation,
+        nodeId,
+        nodeType,
+        data,
+      }),
+    });
+
+    if (!response.ok) {
+      console.error(
+        `[MSW] Webhook failed: ${response.status} ${response.statusText}`
+      );
+    } else {
+      console.log(`[MSW] Webhook sent: ${operation} ${nodeType} ${nodeId}`);
+    }
+  } catch (error) {
+    console.error('[MSW] Failed to send webhook:', error);
+  }
+}
+
+/**
+ * Generate node ID matching the plugin's createNodeId pattern.
+ * Format: {Type}-{id}
+ */
+function createNodeId(type: string, id: string): string {
+  return `${type}-${id}`;
+}
+
+/**
+ * MSW request handlers for the remote todo API.
+ */
+export const remoteTodoHandlers = [
+  // GET /api/todos - List all todos
+  http.get('http://localhost:3001/api/todos', () => {
+    console.log('[MSW] GET /api/todos - returning', todos.length, 'todos');
+    return HttpResponse.json(todos);
+  }),
+
+  // GET /api/todos/:id - Get single todo
+  http.get('http://localhost:3001/api/todos/:id', ({ params }) => {
+    const id = Number(params['id']);
+    const todo = todos.find((t) => t.id === id);
+
+    if (!todo) {
+      return new HttpResponse(null, { status: 404 });
+    }
+
+    return HttpResponse.json(todo);
+  }),
+
+  // POST /api/todos - Create new todo
+  http.post('http://localhost:3001/api/todos', async ({ request }) => {
+    const body = (await request.json()) as {
+      title: string;
+      completed?: boolean;
+    };
+
+    const newTodo: Todo = {
+      id: nextId++,
+      title: body.title,
+      completed: body.completed ?? false,
+    };
+
+    todos.push(newTodo);
+    console.log('[MSW] POST /api/todos - created todo:', newTodo);
+
+    // Send webhook to UDL
+    const nodeId = createNodeId('RemoteTodo', String(newTodo.id));
+    await sendWebhook('create', nodeId, 'RemoteTodo', {
+      todoId: newTodo.id,
+      title: newTodo.title,
+      completed: newTodo.completed,
+    });
+
+    return HttpResponse.json(newTodo, { status: 201 });
+  }),
+
+  // PUT /api/todos/:id - Full update
+  http.put(
+    'http://localhost:3001/api/todos/:id',
+    async ({ params, request }) => {
+      const id = Number(params['id']);
+      const body = (await request.json()) as {
+        title?: string;
+        completed?: boolean;
+      };
+
+      const index = todos.findIndex((t) => t.id === id);
+      if (index === -1) {
+        return new HttpResponse(null, { status: 404 });
+      }
+
+      const existing = todos[index]!;
+      const updatedTodo: Todo = {
+        id,
+        title: body.title ?? existing.title,
+        completed: body.completed ?? existing.completed,
+      };
+      todos[index] = updatedTodo;
+      console.log('[MSW] PUT /api/todos/:id - updated todo:', updatedTodo);
+
+      // Send webhook to UDL
+      const nodeId = createNodeId('RemoteTodo', String(updatedTodo.id));
+      await sendWebhook('update', nodeId, 'RemoteTodo', {
+        todoId: updatedTodo.id,
+        title: updatedTodo.title,
+        completed: updatedTodo.completed,
+      });
+
+      return HttpResponse.json(updatedTodo);
+    }
+  ),
+
+  // PATCH /api/todos/:id - Partial update (e.g., toggle completed)
+  http.patch(
+    'http://localhost:3001/api/todos/:id',
+    async ({ params, request }) => {
+      const id = Number(params['id']);
+      const body = (await request.json()) as {
+        title?: string;
+        completed?: boolean;
+      };
+
+      const index = todos.findIndex((t) => t.id === id);
+      if (index === -1) {
+        return new HttpResponse(null, { status: 404 });
+      }
+
+      const existing = todos[index]!;
+      const updatedTodo: Todo = {
+        id,
+        title: body.title ?? existing.title,
+        completed: body.completed ?? existing.completed,
+      };
+      todos[index] = updatedTodo;
+      console.log('[MSW] PATCH /api/todos/:id - updated todo:', updatedTodo);
+
+      // Send webhook to UDL (upsert for partial updates)
+      const nodeId = createNodeId('RemoteTodo', String(updatedTodo.id));
+      await sendWebhook('upsert', nodeId, 'RemoteTodo', {
+        todoId: updatedTodo.id,
+        title: updatedTodo.title,
+        completed: updatedTodo.completed,
+      });
+
+      return HttpResponse.json(updatedTodo);
+    }
+  ),
+
+  // DELETE /api/todos/:id - Delete todo
+  http.delete('http://localhost:3001/api/todos/:id', async ({ params }) => {
+    const id = Number(params['id']);
+
+    const index = todos.findIndex((t) => t.id === id);
+    if (index === -1) {
+      return new HttpResponse(null, { status: 404 });
+    }
+
+    todos.splice(index, 1);
+    console.log('[MSW] DELETE /api/todos/:id - deleted todo:', id);
+
+    // Send webhook to UDL
+    const nodeId = createNodeId('RemoteTodo', String(id));
+    await sendWebhook('delete', nodeId, 'RemoteTodo');
+
+    return new HttpResponse(null, { status: 204 });
+  }),
+
+  // POST /api/todos/reset - Reset to initial state (for testing)
+  http.post('http://localhost:3001/api/todos/reset', () => {
+    todos = [...initialTodos];
+    nextId = 4;
+    console.log('[MSW] POST /api/todos/reset - reset to initial state');
+    return HttpResponse.json({ reset: true, count: todos.length });
+  }),
+];
+
+// Export for registration with MSW
+export { remoteTodoHandlers as handlers };
diff --git a/packages/core/tests/manual/features/remote-udl-webhooks/plugins/remote-todo-source/udl.config.ts b/packages/core/tests/manual/features/remote-udl-webhooks/plugins/remote-todo-source/udl.config.ts
new file mode 100644
index 0000000..b68fa82
--- /dev/null
+++ b/packages/core/tests/manual/features/remote-udl-webhooks/plugins/remote-todo-source/udl.config.ts
@@ -0,0 +1,75 @@
+/**
+ * Plugin: Remote Todo Source
+ *
+ * This plugin fetches todo items from the MSW-mocked REST API
+ * and creates nodes in the UDL store.
+ *
+ * The REST API is mocked by MSW handlers that also send webhooks
+ * to UDL after each mutation, enabling real-time sync testing.
+ */
+
+import { defineConfig, type SourceNodesContext } from 'universal-data-layer';
+
+// API response type (matches MSW mock structure)
+interface TodoApiResponse {
+  id: number;
+  title: string;
+  completed: boolean;
+}
+
+export const config = defineConfig({
+  type: 'source',
+  name: 'remote-todo-source',
+  // Codegen config - outputs relative to this plugin folder
+  codegen: {
+    output: './generated',
+    guards: true,
+    includeInternal: true,
+  },
+});
+
+/**
+ * Generate a predictable node ID that can be replicated by the browser.
+ * We don't use createNodeId from context because it generates a SHA-256 hash,
+ * which the browser can't easily reproduce for webhook payloads.
+ */
+function makeNodeId(type: string, id: string): string {
+  return `${type}-${id}`;
+}
+
+export async function sourceNodes({
+  actions,
+  createContentDigest,
+}: SourceNodesContext) {
+  // Fetch todos from the MSW-mocked REST API
+  // This URL is intercepted by MSW handlers in mocks/remote-todos.ts
+  const response = await fetch('http://localhost:3001/api/todos');
+
+  if (!response.ok) {
+    throw new Error(`Failed to fetch todos: ${response.statusText}`);
+  }
+
+  const todos: TodoApiResponse[] = await response.json();
+
+  console.log(
+    `[remote-todo-source] Loaded ${todos.length} todos from remote API`
+  );
+
+  for (const todo of todos) {
+    // Use predictable ID format that browser can replicate for webhooks
+    const nodeId = makeNodeId('RemoteTodo', String(todo.id));
+
+    await actions.createNode({
+      internal: {
+        id: nodeId,
+        type: 'RemoteTodo',
+        owner: 'remote-todo-source',
+        contentDigest: createContentDigest(todo),
+      },
+      // Map API fields to node fields
+      todoId: todo.id,
+      title: todo.title,
+      completed: todo.completed,
+    });
+  }
+}
diff --git a/packages/core/tests/manual/features/remote-udl-webhooks/udl.config.ts b/packages/core/tests/manual/features/remote-udl-webhooks/udl.config.ts
new file mode 100644
index 0000000..3556615
--- /dev/null
+++ b/packages/core/tests/manual/features/remote-udl-webhooks/udl.config.ts
@@ -0,0 +1,26 @@
+import { defineConfig } from 'universal-data-layer';
+
+/**
+ * UDL Configuration for Remote UDL Webhooks Demo
+ *
+ * This config demonstrates:
+ * 1. Fetching initial data from an MSW-mocked REST API
+ * 2. Using webhooks to sync CRUD operations to UDL
+ * 3. Testing the remote UDL pattern without a real remote server
+ */
+
+export const config = defineConfig({
+  plugins: [
+    // Remote todo source plugin - fetches from MSW-mocked API
+    {
+      name: './plugins/remote-todo-source',
+      options: {},
+    },
+  ],
+  // Enable default webhook handler for all plugins
+  // This allows the MSW handlers to send webhooks to update UDL nodes
+  defaultWebhook: {
+    enabled: true,
+    path: 'sync', // Endpoint: /_webhooks/remote-todo-source/sync
+  },
+});

From 37dc4831fdf27928dcb64d266c6aff500545d83a Mon Sep 17 00:00:00 2001
From: dawidurbanski <hi@dawidurbanski.com>
Date: Mon, 22 Dec 2025 17:04:47 +0100
Subject: [PATCH 18/46] chore(docs): add version field to package-lock.json

---
 docs/package-lock.json | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/docs/package-lock.json b/docs/package-lock.json
index 391ea09..f547c3a 100644
--- a/docs/package-lock.json
+++ b/docs/package-lock.json
@@ -1,10 +1,12 @@
 {
   "name": "universal-data-layer-docs",
+  "version": "0.0.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "universal-data-layer-docs",
+      "version": "0.0.0",
       "dependencies": {
         "better-sqlite3": "^12.2.0",
         "docus": "latest",

From 35f53e7eba203b4d366d62fc988d2d1f50507e9a Mon Sep 17 00:00:00 2001
From: dawidurbanski <hi@dawidurbanski.com>
Date: Mon, 22 Dec 2025 18:16:50 +0100
Subject: [PATCH 19/46] feat(core): add sync query API for partial updates

Add GET /_sync endpoint that enables clients to query for changes since
a given timestamp. Returns updated nodes and deleted node IDs for
efficient partial sync operations.

- Add defaultDeletionLog singleton following defaultStore pattern
- Create sync handler with SyncResponse interface
- Register /_sync route in server
- Export SyncResponse, defaultDeletionLog, setDefaultDeletionLog
- Add 23 unit tests and 10 integration tests

Closes #65
---
 packages/core/src/handlers/sync.ts            | 107 ++++
 packages/core/src/index.ts                    |   5 +
 packages/core/src/server.ts                   |   6 +
 packages/core/src/sync/defaultDeletionLog.ts  |  50 ++
 .../sync/{deletion-log.ts => deletionLog.ts}  |   0
 packages/core/src/sync/index.ts               |   7 +-
 .../tests/integration/sync-endpoint.test.ts   | 279 ++++++++++
 .../core/tests/unit/handlers/sync.test.ts     | 517 ++++++++++++++++++
 .../core/tests/unit/sync/deletion-log.test.ts |   2 +-
 9 files changed, 971 insertions(+), 2 deletions(-)
 create mode 100644 packages/core/src/handlers/sync.ts
 create mode 100644 packages/core/src/sync/defaultDeletionLog.ts
 rename packages/core/src/sync/{deletion-log.ts => deletionLog.ts} (100%)
 create mode 100644 packages/core/tests/integration/sync-endpoint.test.ts
 create mode 100644 packages/core/tests/unit/handlers/sync.test.ts

diff --git a/packages/core/src/handlers/sync.ts b/packages/core/src/handlers/sync.ts
new file mode 100644
index 0000000..f07295c
--- /dev/null
+++ b/packages/core/src/handlers/sync.ts
@@ -0,0 +1,107 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { URL } from 'node:url';
+import { defaultStore } from '@/nodes/defaultStore.js';
+import { defaultDeletionLog } from '@/sync/index.js';
+import type { Node } from '@/nodes/types.js';
+
+/**
+ * Response format for the sync endpoint.
+ * Contains updated nodes, deleted node IDs, and metadata for the next sync.
+ */
+export interface SyncResponse {
+  /** Nodes created or updated since the given timestamp */
+  updated: Node[];
+  /** Node IDs deleted since the given timestamp */
+  deleted: {
+    nodeId: string;
+    nodeType: string;
+    deletedAt: string;
+  }[];
+  /** Server timestamp for the next sync (use as `since` for subsequent calls) */
+  serverTime: string;
+  /** Whether there are more updates (pagination - not implemented yet) */
+  hasMore: boolean;
+}
+
+/**
+ * Sync endpoint handler.
+ * Returns nodes updated and deleted since a given timestamp.
+ *
+ * @example
+ * ```
+ * GET /_sync?since=2024-01-01T00:00:00Z
+ * GET /_sync?since=2024-01-01T00:00:00Z&types=Product,Collection
+ * ```
+ *
+ * @param req - HTTP request
+ * @param res - HTTP response
+ */
+export function syncHandler(req: IncomingMessage, res: ServerResponse): void {
+  if (req.method !== 'GET') {
+    res.writeHead(405, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: 'Method not allowed' }));
+    return;
+  }
+
+  const url = new URL(req.url!, `http://${req.headers.host}`);
+  const since = url.searchParams.get('since');
+  const typesParam = url.searchParams.get('types');
+
+  if (!since) {
+    res.writeHead(400, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: 'Missing required parameter: since' }));
+    return;
+  }
+
+  let sinceDate: Date;
+  try {
+    sinceDate = new Date(since);
+    if (isNaN(sinceDate.getTime())) {
+      throw new Error('Invalid date');
+    }
+  } catch {
+    res.writeHead(400, { 'Content-Type': 'application/json' });
+    res.end(
+      JSON.stringify({ error: 'Invalid date format for since parameter' })
+    );
+    return;
+  }
+
+  const types = typesParam ? typesParam.split(',').map((t) => t.trim()) : null;
+  const sinceMs = sinceDate.getTime();
+
+  // Get updated nodes
+  let allNodes = defaultStore.getAll();
+
+  // Filter by type if specified
+  if (types) {
+    allNodes = allNodes.filter((node) => types.includes(node.internal.type));
+  }
+
+  // Filter by modifiedAt (nodes updated after the since timestamp)
+  const updated = allNodes.filter((node) => {
+    const modifiedAt = node.internal.modifiedAt;
+    if (!modifiedAt) return false;
+    return modifiedAt > sinceMs;
+  });
+
+  // Get deleted nodes
+  const deletedEntries = defaultDeletionLog.getDeletedSince(sinceDate);
+  const filteredDeleted = types
+    ? deletedEntries.filter((entry) => types.includes(entry.nodeType))
+    : deletedEntries;
+
+  const response: SyncResponse = {
+    updated,
+    deleted: filteredDeleted.map((entry) => ({
+      nodeId: entry.nodeId,
+      nodeType: entry.nodeType,
+      deletedAt: entry.deletedAt,
+    })),
+    serverTime: new Date().toISOString(),
+    hasMore: false,
+  };
+
+  res.writeHead(200, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify(response));
+}
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 9e3b729..e02927c 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -96,8 +96,13 @@ export {
   type DeletionLogEntry,
   type DeletionLogData,
   type DeletionNodeInfo,
+  defaultDeletionLog,
+  setDefaultDeletionLog,
 } from './sync/index.js';
 
+// Re-export sync handler types
+export { type SyncResponse } from './handlers/sync.js';
+
 // Re-export env utilities
 export { loadEnv, type LoadEnvOptions, type LoadEnvResult } from './env.js';
 
diff --git a/packages/core/src/server.ts b/packages/core/src/server.ts
index f24fe40..ae8511d 100644
--- a/packages/core/src/server.ts
+++ b/packages/core/src/server.ts
@@ -4,6 +4,7 @@ import graphqlHandler from '@/handlers/graphql.js';
 import graphiqlHandler from '@/handlers/graphiql.js';
 import { healthHandler, readyHandler } from '@/handlers/health.js';
 import { isWebhookRequest, webhookHandler } from '@/handlers/webhook.js';
+import { syncHandler } from '@/handlers/sync.js';
 
 const server = createServer((req, res) => {
   // Add CORS headers for all requests
@@ -25,6 +26,11 @@ const server = createServer((req, res) => {
     return readyHandler(req, res);
   }
 
+  // Sync endpoint for partial updates
+  if (req.url?.startsWith('/_sync')) {
+    return syncHandler(req, res);
+  }
+
   // Webhook endpoints
   if (req.url && isWebhookRequest(req.url)) {
     return webhookHandler(req, res);
diff --git a/packages/core/src/sync/defaultDeletionLog.ts b/packages/core/src/sync/defaultDeletionLog.ts
new file mode 100644
index 0000000..9d4c0fb
--- /dev/null
+++ b/packages/core/src/sync/defaultDeletionLog.ts
@@ -0,0 +1,50 @@
+import { DeletionLog } from './deletionLog.js';
+
+/**
+ * Default singleton deletion log instance.
+ * This is automatically created on first import and persists across the application.
+ * All plugins using the default behavior will share this deletion log.
+ *
+ * @example
+ * ```ts
+ * // In your application - all modules get the same deletion log instance
+ * import { defaultDeletionLog } from 'universal-data-layer';
+ *
+ * // Record a deletion
+ * defaultDeletionLog.recordDeletion(node);
+ *
+ * // Query deletions since a timestamp
+ * const deleted = defaultDeletionLog.getDeletedSince('2024-01-01T00:00:00.000Z');
+ * ```
+ *
+ * @example
+ * ```ts
+ * // For testing - replace with a fresh deletion log
+ * import { defaultDeletionLog, setDefaultDeletionLog } from 'universal-data-layer';
+ *
+ * beforeEach(() => {
+ *   setDefaultDeletionLog(new DeletionLog());
+ * });
+ * ```
+ */
+export let defaultDeletionLog: DeletionLog = new DeletionLog();
+
+/**
+ * Replace the default deletion log with a new instance.
+ * Useful for testing to ensure isolation between test runs.
+ *
+ * @param log - The new deletion log to use as the default
+ *
+ * @example
+ * ```ts
+ * import { setDefaultDeletionLog, DeletionLog } from 'universal-data-layer';
+ *
+ * // In test setup
+ * beforeEach(() => {
+ *   setDefaultDeletionLog(new DeletionLog());
+ * });
+ * ```
+ */
+export function setDefaultDeletionLog(log: DeletionLog): void {
+  defaultDeletionLog = log;
+}
diff --git a/packages/core/src/sync/deletion-log.ts b/packages/core/src/sync/deletionLog.ts
similarity index 100%
rename from packages/core/src/sync/deletion-log.ts
rename to packages/core/src/sync/deletionLog.ts
diff --git a/packages/core/src/sync/index.ts b/packages/core/src/sync/index.ts
index 0b523b1..6019738 100644
--- a/packages/core/src/sync/index.ts
+++ b/packages/core/src/sync/index.ts
@@ -3,4 +3,9 @@ export {
   type DeletionLogEntry,
   type DeletionLogData,
   type DeletionNodeInfo,
-} from './deletion-log.js';
+} from './deletionLog.js';
+
+export {
+  defaultDeletionLog,
+  setDefaultDeletionLog,
+} from './defaultDeletionLog.js';
diff --git a/packages/core/tests/integration/sync-endpoint.test.ts b/packages/core/tests/integration/sync-endpoint.test.ts
new file mode 100644
index 0000000..5154798
--- /dev/null
+++ b/packages/core/tests/integration/sync-endpoint.test.ts
@@ -0,0 +1,279 @@
+import { describe, it, expect, beforeAll, afterAll, beforeEach } from 'vitest';
+import http, { createServer, type Server } from 'node:http';
+import { syncHandler } from '@/handlers/sync.js';
+import { setDefaultStore, NodeStore } from '@/nodes/index.js';
+import { setDefaultDeletionLog, DeletionLog } from '@/sync/index.js';
+import type { Node } from '@/nodes/types.js';
+
+function makeRequest(
+  server: Server,
+  path: string,
+  method: string = 'GET'
+): Promise<{
+  statusCode: number;
+  headers: Record<string, string>;
+  body: string;
+}> {
+  return new Promise((resolve, reject) => {
+    const address = server.address();
+    if (!address || typeof address === 'string') {
+      reject(new Error('Server address not available'));
+      return;
+    }
+
+    const req = http.request(
+      {
+        hostname: 'localhost',
+        port: address.port,
+        path,
+        method,
+      },
+      (res: {
+        statusCode: number;
+        headers: Record<string, string>;
+        on: (event: string, callback: (data?: Buffer) => void) => void;
+      }) => {
+        let body = '';
+        res.on('data', (chunk: Buffer) => {
+          body += chunk.toString();
+        });
+        res.on('end', () => {
+          resolve({
+            statusCode: res.statusCode,
+            headers: res.headers as Record<string, string>,
+            body,
+          });
+        });
+      }
+    );
+    req.on('error', reject);
+    req.end();
+  });
+}
+
+function createTestNode(overrides: {
+  id: string;
+  type: string;
+  modifiedAt: number;
+}): Node {
+  return {
+    internal: {
+      id: overrides.id,
+      type: overrides.type,
+      contentDigest: 'digest-' + overrides.id,
+      owner: 'test-plugin',
+      createdAt: overrides.modifiedAt,
+      modifiedAt: overrides.modifiedAt,
+    },
+    name: 'Test ' + overrides.id,
+  } as Node;
+}
+
+describe('sync endpoint integration', () => {
+  let server: Server;
+  let store: NodeStore;
+  let deletionLog: DeletionLog;
+
+  beforeAll(() => {
+    server = createServer((req, res) => {
+      // Add CORS headers
+      res.setHeader('Access-Control-Allow-Origin', '*');
+      res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+      res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+
+      if (req.url?.startsWith('/_sync')) {
+        return syncHandler(req, res);
+      }
+
+      res.writeHead(404);
+      res.end('Not found');
+    });
+
+    return new Promise<void>((resolve) => {
+      server.listen(0, () => resolve());
+    });
+  });
+
+  afterAll(() => {
+    return new Promise<void>((resolve) => {
+      server.close(() => resolve());
+    });
+  });
+
+  beforeEach(() => {
+    store = new NodeStore();
+    setDefaultStore(store);
+
+    deletionLog = new DeletionLog();
+    setDefaultDeletionLog(deletionLog);
+  });
+
+  describe('/_sync endpoint', () => {
+    it('should return 200 with JSON response', async () => {
+      const response = await makeRequest(
+        server,
+        '/_sync?since=2024-01-01T00:00:00Z'
+      );
+
+      expect(response.statusCode).toBe(200);
+      expect(response.headers['content-type']).toBe('application/json');
+
+      const body = JSON.parse(response.body);
+      expect(body).toHaveProperty('updated');
+      expect(body).toHaveProperty('deleted');
+      expect(body).toHaveProperty('serverTime');
+      expect(body).toHaveProperty('hasMore');
+    });
+
+    it('should include CORS headers', async () => {
+      const response = await makeRequest(
+        server,
+        '/_sync?since=2024-01-01T00:00:00Z'
+      );
+
+      expect(response.headers['access-control-allow-origin']).toBe('*');
+      expect(response.headers['access-control-allow-methods']).toBe(
+        'GET, POST, OPTIONS'
+      );
+    });
+
+    it('should return updated nodes after timestamp', async () => {
+      // Add a node modified after 2024-01-01
+      store.set(
+        createTestNode({
+          id: 'product-1',
+          type: 'Product',
+          modifiedAt: new Date('2024-06-01T00:00:00Z').getTime(),
+        })
+      );
+
+      const response = await makeRequest(
+        server,
+        '/_sync?since=2024-01-01T00:00:00Z'
+      );
+
+      expect(response.statusCode).toBe(200);
+      const body = JSON.parse(response.body);
+      expect(body.updated).toHaveLength(1);
+      expect(body.updated[0].internal.id).toBe('product-1');
+    });
+
+    it('should return deleted nodes after timestamp', async () => {
+      // Record a deletion
+      deletionLog.recordDeletion({
+        internal: {
+          id: 'deleted-product-1',
+          type: 'Product',
+          owner: 'test-plugin',
+        },
+      });
+
+      const response = await makeRequest(
+        server,
+        '/_sync?since=2024-01-01T00:00:00Z'
+      );
+
+      expect(response.statusCode).toBe(200);
+      const body = JSON.parse(response.body);
+      expect(body.deleted).toHaveLength(1);
+      expect(body.deleted[0].nodeId).toBe('deleted-product-1');
+      expect(body.deleted[0].nodeType).toBe('Product');
+    });
+
+    it('should filter by types parameter', async () => {
+      store.set(
+        createTestNode({
+          id: 'product-1',
+          type: 'Product',
+          modifiedAt: new Date('2024-06-01T00:00:00Z').getTime(),
+        })
+      );
+      store.set(
+        createTestNode({
+          id: 'collection-1',
+          type: 'Collection',
+          modifiedAt: new Date('2024-06-01T00:00:00Z').getTime(),
+        })
+      );
+
+      const response = await makeRequest(
+        server,
+        '/_sync?since=2024-01-01T00:00:00Z&types=Product'
+      );
+
+      expect(response.statusCode).toBe(200);
+      const body = JSON.parse(response.body);
+      expect(body.updated).toHaveLength(1);
+      expect(body.updated[0].internal.type).toBe('Product');
+    });
+
+    it('should return 400 when since parameter is missing', async () => {
+      const response = await makeRequest(server, '/_sync');
+
+      expect(response.statusCode).toBe(400);
+      const body = JSON.parse(response.body);
+      expect(body.error).toBe('Missing required parameter: since');
+    });
+
+    it('should return 400 for invalid date format', async () => {
+      const response = await makeRequest(server, '/_sync?since=invalid');
+
+      expect(response.statusCode).toBe(400);
+      const body = JSON.parse(response.body);
+      expect(body.error).toBe('Invalid date format for since parameter');
+    });
+
+    it('should return 405 for POST request', async () => {
+      const response = await makeRequest(
+        server,
+        '/_sync?since=2024-01-01T00:00:00Z',
+        'POST'
+      );
+
+      expect(response.statusCode).toBe(405);
+      const body = JSON.parse(response.body);
+      expect(body.error).toBe('Method not allowed');
+    });
+
+    it('should return valid ISO 8601 serverTime', async () => {
+      const response = await makeRequest(
+        server,
+        '/_sync?since=2024-01-01T00:00:00Z'
+      );
+
+      const body = JSON.parse(response.body);
+      const timestamp = new Date(body.serverTime);
+      expect(timestamp.toISOString()).toBe(body.serverTime);
+    });
+
+    it('should use serverTime for subsequent sync calls', async () => {
+      // First sync
+      const response1 = await makeRequest(
+        server,
+        '/_sync?since=2024-01-01T00:00:00Z'
+      );
+      const body1 = JSON.parse(response1.body);
+      const serverTime = body1.serverTime;
+
+      // Add a new node after first sync (add 1ms to ensure it's after serverTime)
+      const serverTimeMs = new Date(serverTime).getTime();
+      store.set(
+        createTestNode({
+          id: 'new-product',
+          type: 'Product',
+          modifiedAt: serverTimeMs + 1,
+        })
+      );
+
+      // Second sync using serverTime from first response
+      const response2 = await makeRequest(
+        server,
+        `/_sync?since=${encodeURIComponent(serverTime)}`
+      );
+      const body2 = JSON.parse(response2.body);
+
+      expect(body2.updated).toHaveLength(1);
+      expect(body2.updated[0].internal.id).toBe('new-product');
+    });
+  });
+});
diff --git a/packages/core/tests/unit/handlers/sync.test.ts b/packages/core/tests/unit/handlers/sync.test.ts
new file mode 100644
index 0000000..b827f55
--- /dev/null
+++ b/packages/core/tests/unit/handlers/sync.test.ts
@@ -0,0 +1,517 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { syncHandler } from '@/handlers/sync.js';
+import { setDefaultStore, NodeStore } from '@/nodes/index.js';
+import { setDefaultDeletionLog, DeletionLog } from '@/sync/index.js';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { Node } from '@/nodes/types.js';
+
+function createMockRequest(
+  method: string = 'GET',
+  url: string = '/_sync?since=2024-01-01T00:00:00Z'
+): IncomingMessage {
+  return {
+    method,
+    url,
+    headers: {
+      host: 'localhost:4000',
+    },
+  } as IncomingMessage;
+}
+
+function createMockResponse(): ServerResponse & {
+  _statusCode: number;
+  _headers: Record<string, string>;
+  _body: string;
+} {
+  const res = {
+    _statusCode: 0,
+    _headers: {} as Record<string, string>,
+    _body: '',
+    writeHead(statusCode: number, headers?: Record<string, string>) {
+      this._statusCode = statusCode;
+      if (headers) {
+        Object.assign(this._headers, headers);
+      }
+      return this;
+    },
+    end(body?: string) {
+      if (body) {
+        this._body = body;
+      }
+    },
+  };
+  return res as unknown as ServerResponse & {
+    _statusCode: number;
+    _headers: Record<string, string>;
+    _body: string;
+  };
+}
+
+function createTestNode(
+  overrides: Partial<Node> & { internal: Partial<Node['internal']> }
+): Node {
+  const now = Date.now();
+  return {
+    internal: {
+      id: 'test-id',
+      type: 'TestType',
+      contentDigest: 'digest123',
+      owner: 'test-plugin',
+      createdAt: now,
+      modifiedAt: now,
+      ...overrides.internal,
+    },
+    ...overrides,
+  } as Node;
+}
+
+describe('syncHandler', () => {
+  let store: NodeStore;
+  let deletionLog: DeletionLog;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date('2024-06-15T12:00:00.000Z'));
+
+    store = new NodeStore();
+    setDefaultStore(store);
+
+    deletionLog = new DeletionLog();
+    setDefaultDeletionLog(deletionLog);
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  describe('valid sync request', () => {
+    it('should return 200 with correct response format', () => {
+      const req = createMockRequest('GET', '/_sync?since=2024-01-01T00:00:00Z');
+      const res = createMockResponse();
+
+      syncHandler(req, res);
+
+      expect(res._statusCode).toBe(200);
+      expect(res._headers['Content-Type']).toBe('application/json');
+
+      const body = JSON.parse(res._body);
+      expect(body).toHaveProperty('updated');
+      expect(body).toHaveProperty('deleted');
+      expect(body).toHaveProperty('serverTime');
+      expect(body).toHaveProperty('hasMore');
+      expect(Array.isArray(body.updated)).toBe(true);
+      expect(Array.isArray(body.deleted)).toBe(true);
+      expect(body.hasMore).toBe(false);
+    });
+
+    it('should return updated nodes after timestamp', () => {
+      // Node modified after the since timestamp
+      const node = createTestNode({
+        internal: {
+          id: 'node-1',
+          type: 'Product',
+          modifiedAt: new Date('2024-06-01T00:00:00Z').getTime(),
+        },
+      });
+      store.set(node);
+
+      const req = createMockRequest('GET', '/_sync?since=2024-01-01T00:00:00Z');
+      const res = createMockResponse();
+
+      syncHandler(req, res);
+
+      const body = JSON.parse(res._body);
+      expect(body.updated).toHaveLength(1);
+      expect(body.updated[0].internal.id).toBe('node-1');
+    });
+
+    it('should not return nodes before timestamp', () => {
+      // Node modified before the since timestamp
+      const node = createTestNode({
+        internal: {
+          id: 'node-1',
+          type: 'Product',
+          modifiedAt: new Date('2023-06-01T00:00:00Z').getTime(),
+        },
+      });
+      store.set(node);
+
+      const req = createMockRequest('GET', '/_sync?since=2024-01-01T00:00:00Z');
+      const res = createMockResponse();
+
+      syncHandler(req, res);
+
+      const body = JSON.parse(res._body);
+      expect(body.updated).toHaveLength(0);
+    });
+
+    it('should return deleted nodes after timestamp', () => {
+      const mockNode = {
+        internal: {
+          id: 'deleted-node-1',
+          type: 'Product',
+          owner: 'test-plugin',
+        },
+      };
+      deletionLog.recordDeletion(mockNode);
+
+      const req = createMockRequest('GET', '/_sync?since=2024-01-01T00:00:00Z');
+      const res = createMockResponse();
+
+      syncHandler(req, res);
+
+      const body = JSON.parse(res._body);
+      expect(body.deleted).toHaveLength(1);
+      expect(body.deleted[0].nodeId).toBe('deleted-node-1');
+      expect(body.deleted[0].nodeType).toBe('Product');
+      expect(body.deleted[0].deletedAt).toBeDefined();
+    });
+
+    it('should include serverTime in response', () => {
+      const req = createMockRequest('GET', '/_sync?since=2024-01-01T00:00:00Z');
+      const res = createMockResponse();
+
+      syncHandler(req, res);
+
+      const body = JSON.parse(res._body);
+      expect(body.serverTime).toBe('2024-06-15T12:00:00.000Z');
+    });
+
+    it('should return valid ISO 8601 serverTime', () => {
+      const req = createMockRequest('GET', '/_sync?since=2024-01-01T00:00:00Z');
+      const res = createMockResponse();
+
+      syncHandler(req, res);
+
+      const body = JSON.parse(res._body);
+      const timestamp = new Date(body.serverTime);
+      expect(timestamp.toISOString()).toBe(body.serverTime);
+    });
+  });
+
+  describe('parameter validation', () => {
+    it('should return 400 when since parameter is missing', () => {
+      const req = createMockRequest('GET', '/_sync');
+      const res = createMockResponse();
+
+      syncHandler(req, res);
+
+      expect(res._statusCode).toBe(400);
+      const body = JSON.parse(res._body);
+      expect(body.error).toBe('Missing required parameter: since');
+    });
+
+    it('should return 400 for invalid date format', () => {
+      const req = createMockRequest('GET', '/_sync?since=invalid-date');
+      const res = createMockResponse();
+
+      syncHandler(req, res);
+
+      expect(res._statusCode).toBe(400);
+      const body = JSON.parse(res._body);
+      expect(body.error).toBe('Invalid date format for since parameter');
+    });
+
+    it('should return 400 for empty since value', () => {
+      const req = createMockRequest('GET', '/_sync?since=');
+      const res = createMockResponse();
+
+      syncHandler(req, res);
+
+      expect(res._statusCode).toBe(400);
+      const body = JSON.parse(res._body);
+      expect(body.error).toBe('Missing required parameter: since');
+    });
+  });
+
+  describe('type filtering', () => {
+    beforeEach(() => {
+      // Add nodes of different types
+      store.set(
+        createTestNode({
+          internal: {
+            id: 'product-1',
+            type: 'Product',
+            modifiedAt: new Date('2024-06-01T00:00:00Z').getTime(),
+          },
+        })
+      );
+      store.set(
+        createTestNode({
+          internal: {
+            id: 'collection-1',
+            type: 'Collection',
+            modifiedAt: new Date('2024-06-01T00:00:00Z').getTime(),
+          },
+        })
+      );
+      store.set(
+        createTestNode({
+          internal: {
+            id: 'category-1',
+            type: 'Category',
+            modifiedAt: new Date('2024-06-01T00:00:00Z').getTime(),
+          },
+        })
+      );
+
+      // Add deletions of different types
+      deletionLog.recordDeletion({
+        internal: { id: 'deleted-product', type: 'Product', owner: 'test' },
+      });
+      deletionLog.recordDeletion({
+        internal: {
+          id: 'deleted-collection',
+          type: 'Collection',
+          owner: 'test',
+        },
+      });
+    });
+
+    it('should filter updated nodes by single type', () => {
+      const req = createMockRequest(
+        'GET',
+        '/_sync?since=2024-01-01T00:00:00Z&types=Product'
+      );
+      const res = createMockResponse();
+
+      syncHandler(req, res);
+
+      const body = JSON.parse(res._body);
+      expect(body.updated).toHaveLength(1);
+      expect(body.updated[0].internal.type).toBe('Product');
+    });
+
+    it('should filter updated nodes by multiple types', () => {
+      const req = createMockRequest(
+        'GET',
+        '/_sync?since=2024-01-01T00:00:00Z&types=Product,Collection'
+      );
+      const res = createMockResponse();
+
+      syncHandler(req, res);
+
+      const body = JSON.parse(res._body);
+      expect(body.updated).toHaveLength(2);
+      const types = body.updated.map((n: Node) => n.internal.type);
+      expect(types).toContain('Product');
+      expect(types).toContain('Collection');
+    });
+
+    it('should filter deleted nodes by type', () => {
+      const req = createMockRequest(
+        'GET',
+        '/_sync?since=2024-01-01T00:00:00Z&types=Product'
+      );
+      const res = createMockResponse();
+
+      syncHandler(req, res);
+
+      const body = JSON.parse(res._body);
+      expect(body.deleted).toHaveLength(1);
+      expect(body.deleted[0].nodeType).toBe('Product');
+    });
+
+    it('should handle types with spaces after comma', () => {
+      const req = createMockRequest(
+        'GET',
+        '/_sync?since=2024-01-01T00:00:00Z&types=Product, Collection'
+      );
+      const res = createMockResponse();
+
+      syncHandler(req, res);
+
+      const body = JSON.parse(res._body);
+      expect(body.updated).toHaveLength(2);
+    });
+  });
+
+  describe('method validation', () => {
+    it('should return 405 for POST request', () => {
+      const req = createMockRequest(
+        'POST',
+        '/_sync?since=2024-01-01T00:00:00Z'
+      );
+      const res = createMockResponse();
+
+      syncHandler(req, res);
+
+      expect(res._statusCode).toBe(405);
+      const body = JSON.parse(res._body);
+      expect(body.error).toBe('Method not allowed');
+    });
+
+    it('should return 405 for PUT request', () => {
+      const req = createMockRequest('PUT', '/_sync?since=2024-01-01T00:00:00Z');
+      const res = createMockResponse();
+
+      syncHandler(req, res);
+
+      expect(res._statusCode).toBe(405);
+    });
+
+    it('should return 405 for DELETE request', () => {
+      const req = createMockRequest(
+        'DELETE',
+        '/_sync?since=2024-01-01T00:00:00Z'
+      );
+      const res = createMockResponse();
+
+      syncHandler(req, res);
+
+      expect(res._statusCode).toBe(405);
+    });
+  });
+
+  describe('edge cases', () => {
+    it('should return empty arrays when store is empty', () => {
+      const req = createMockRequest('GET', '/_sync?since=2024-01-01T00:00:00Z');
+      const res = createMockResponse();
+
+      syncHandler(req, res);
+
+      const body = JSON.parse(res._body);
+      expect(body.updated).toHaveLength(0);
+      expect(body.deleted).toHaveLength(0);
+    });
+
+    it('should return empty deleted array when deletion log is empty', () => {
+      store.set(
+        createTestNode({
+          internal: {
+            id: 'node-1',
+            type: 'Product',
+            modifiedAt: new Date('2024-06-01T00:00:00Z').getTime(),
+          },
+        })
+      );
+
+      const req = createMockRequest('GET', '/_sync?since=2024-01-01T00:00:00Z');
+      const res = createMockResponse();
+
+      syncHandler(req, res);
+
+      const body = JSON.parse(res._body);
+      expect(body.updated).toHaveLength(1);
+      expect(body.deleted).toHaveLength(0);
+    });
+
+    it('should exclude nodes at exactly the since timestamp', () => {
+      const exactTimestamp = new Date('2024-01-01T00:00:00Z').getTime();
+      store.set(
+        createTestNode({
+          internal: {
+            id: 'node-1',
+            type: 'Product',
+            modifiedAt: exactTimestamp,
+          },
+        })
+      );
+
+      const req = createMockRequest('GET', '/_sync?since=2024-01-01T00:00:00Z');
+      const res = createMockResponse();
+
+      syncHandler(req, res);
+
+      const body = JSON.parse(res._body);
+      expect(body.updated).toHaveLength(0);
+    });
+
+    it('should include nodes 1ms after the since timestamp', () => {
+      const justAfterTimestamp = new Date('2024-01-01T00:00:00.001Z').getTime();
+      store.set(
+        createTestNode({
+          internal: {
+            id: 'node-1',
+            type: 'Product',
+            modifiedAt: justAfterTimestamp,
+          },
+        })
+      );
+
+      const req = createMockRequest('GET', '/_sync?since=2024-01-01T00:00:00Z');
+      const res = createMockResponse();
+
+      syncHandler(req, res);
+
+      const body = JSON.parse(res._body);
+      expect(body.updated).toHaveLength(1);
+    });
+
+    it('should handle nodes without modifiedAt', () => {
+      const nodeWithoutModifiedAt = {
+        internal: {
+          id: 'node-1',
+          type: 'Product',
+          contentDigest: 'digest',
+          owner: 'test',
+          createdAt: Date.now(),
+          modifiedAt: undefined,
+        },
+      } as unknown as Node;
+      store.set(nodeWithoutModifiedAt);
+
+      const req = createMockRequest('GET', '/_sync?since=2024-01-01T00:00:00Z');
+      const res = createMockResponse();
+
+      syncHandler(req, res);
+
+      const body = JSON.parse(res._body);
+      expect(body.updated).toHaveLength(0);
+    });
+
+    it('should return empty updated when no nodes match timestamp filter', () => {
+      // All nodes before since timestamp
+      store.set(
+        createTestNode({
+          internal: {
+            id: 'node-1',
+            type: 'Product',
+            modifiedAt: new Date('2023-01-01T00:00:00Z').getTime(),
+          },
+        })
+      );
+      store.set(
+        createTestNode({
+          internal: {
+            id: 'node-2',
+            type: 'Collection',
+            modifiedAt: new Date('2023-06-01T00:00:00Z').getTime(),
+          },
+        })
+      );
+
+      const req = createMockRequest('GET', '/_sync?since=2024-01-01T00:00:00Z');
+      const res = createMockResponse();
+
+      syncHandler(req, res);
+
+      const body = JSON.parse(res._body);
+      expect(body.updated).toHaveLength(0);
+    });
+
+    it('should handle type filter with non-existent types', () => {
+      store.set(
+        createTestNode({
+          internal: {
+            id: 'node-1',
+            type: 'Product',
+            modifiedAt: new Date('2024-06-01T00:00:00Z').getTime(),
+          },
+        })
+      );
+
+      const req = createMockRequest(
+        'GET',
+        '/_sync?since=2024-01-01T00:00:00Z&types=NonExistent'
+      );
+      const res = createMockResponse();
+
+      syncHandler(req, res);
+
+      const body = JSON.parse(res._body);
+      expect(body.updated).toHaveLength(0);
+      expect(body.deleted).toHaveLength(0);
+    });
+  });
+});
diff --git a/packages/core/tests/unit/sync/deletion-log.test.ts b/packages/core/tests/unit/sync/deletion-log.test.ts
index 87883a3..eea3420 100644
--- a/packages/core/tests/unit/sync/deletion-log.test.ts
+++ b/packages/core/tests/unit/sync/deletion-log.test.ts
@@ -3,7 +3,7 @@ import {
   DeletionLog,
   type DeletionLogData,
   type DeletionNodeInfo,
-} from '@/sync/deletion-log.js';
+} from '@/sync/deletionLog.js';
 
 /** Helper to create a mock node for testing */
 function createMockNode(

From 8a532b915310649cf9486fecc96a5081942eeb39 Mon Sep 17 00:00:00 2001
From: dawidurbanski <hi@dawidurbanski.com>
Date: Mon, 22 Dec 2025 18:47:41 +0100
Subject: [PATCH 20/46] feat(core): add WebSocket server for real-time node
 change notifications

Implement an opt-in WebSocket server that broadcasts node changes to
connected clients immediately when nodes are created, updated, or deleted.

- Add WebSocketConfig to RemoteConfig with enabled, port, path, and
  heartbeatIntervalMs options
- Create node event emitter that fires on createNode, deleteNode, and
  extendNode actions
- Implement UDLWebSocketServer class with subscription filtering,
  heartbeat for connection health, and graceful shutdown
- Integrate WebSocket server initialization in start-server.ts
- Add 31 unit and integration tests for events and WebSocket server

Clients can subscribe to specific node types or all types (*) and
receive full node data in real-time, enabling local dev machines to
receive updates immediately when webhooks modify the data layer.

Closes #66
---
 package-lock.json                             |  33 ++
 packages/core/package.json                    |   2 +
 packages/core/src/index.ts                    |  19 +
 packages/core/src/loader.ts                   |  60 +++
 packages/core/src/nodes/actions/createNode.ts |  10 +
 packages/core/src/nodes/actions/deleteNode.ts |  10 +
 packages/core/src/nodes/actions/extendNode.ts |  10 +
 packages/core/src/nodes/events.ts             |  76 ++++
 packages/core/src/nodes/index.ts              |   9 +
 packages/core/src/start-server.ts             |  29 +-
 packages/core/src/websocket/index.ts          |  40 ++
 packages/core/src/websocket/server.ts         | 297 +++++++++++++
 .../core/tests/integration/websocket.test.ts  | 404 ++++++++++++++++++
 packages/core/tests/unit/nodes/events.test.ts | 215 ++++++++++
 .../core/tests/unit/websocket/server.test.ts  | 376 ++++++++++++++++
 15 files changed, 1589 insertions(+), 1 deletion(-)
 create mode 100644 packages/core/src/nodes/events.ts
 create mode 100644 packages/core/src/websocket/index.ts
 create mode 100644 packages/core/src/websocket/server.ts
 create mode 100644 packages/core/tests/integration/websocket.test.ts
 create mode 100644 packages/core/tests/unit/nodes/events.test.ts
 create mode 100644 packages/core/tests/unit/websocket/server.test.ts

diff --git a/package-lock.json b/package-lock.json
index 0f34f86..408879c 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -3342,6 +3342,16 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/@types/ws": {
+      "version": "8.18.1",
+      "resolved": "https://registry.npmjs.org/@types/ws/-/ws-8.18.1.tgz",
+      "integrity": "sha512-ThVF6DCVhA8kUGy+aazFQ4kXQ7E1Ty7A3ypFOe0IcJV8O/M511G99AW24irKrW56Wt44yG9+ij8FaqoBGkuBXg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/node": "*"
+      }
+    },
     "node_modules/@typescript-eslint/eslint-plugin": {
       "version": "8.50.0",
       "resolved": "https://registry.npmjs.org/@typescript-eslint/eslint-plugin/-/eslint-plugin-8.50.0.tgz",
@@ -11769,6 +11779,27 @@
         "url": "https://github.com/chalk/strip-ansi?sponsor=1"
       }
     },
+    "node_modules/ws": {
+      "version": "8.18.3",
+      "resolved": "https://registry.npmjs.org/ws/-/ws-8.18.3.tgz",
+      "integrity": "sha512-PEIGCY5tSlUt50cqyMXfCzX+oOPqN0vuGqWzbcJ2xvnkzkq46oOpz7dQaTDBdfICb4N14+GARUDw2XV2N4tvzg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=10.0.0"
+      },
+      "peerDependencies": {
+        "bufferutil": "^4.0.1",
+        "utf-8-validate": ">=5.0.2"
+      },
+      "peerDependenciesMeta": {
+        "bufferutil": {
+          "optional": true
+        },
+        "utf-8-validate": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/y18n": {
       "version": "5.0.8",
       "resolved": "https://registry.npmjs.org/y18n/-/y18n-5.0.8.tgz",
@@ -11940,6 +11971,7 @@
         "pluralize": "^8.0.0",
         "ruru": "^2.0.0-beta.30",
         "tsx": "^4.19.2",
+        "ws": "^8.18.3",
         "zod": "^4.1.13"
       },
       "bin": {
@@ -11948,6 +11980,7 @@
       },
       "devDependencies": {
         "@types/pluralize": "^0.0.33",
+        "@types/ws": "^8.18.1",
         "msw": "^2.7.0"
       }
     },
diff --git a/packages/core/package.json b/packages/core/package.json
index dfad770..a95de2d 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -59,10 +59,12 @@
     "pluralize": "^8.0.0",
     "ruru": "^2.0.0-beta.30",
     "tsx": "^4.19.2",
+    "ws": "^8.18.3",
     "zod": "^4.1.13"
   },
   "devDependencies": {
     "@types/pluralize": "^0.0.33",
+    "@types/ws": "^8.18.1",
     "msw": "^2.7.0"
   }
 }
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index e02927c..517026c 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -157,5 +157,24 @@ export {
   registerDefaultWebhooks,
 } from './webhooks/index.js';
 
+// Re-export WebSocket server utilities
+export {
+  UDLWebSocketServer,
+  getDefaultWebSocketServer,
+  setDefaultWebSocketServer,
+  type ServerMessage,
+  type NodeChangeMessage,
+  type SubscribedMessage,
+  type PongMessage,
+  type ConnectedMessage,
+  type ClientMessage,
+  type SubscribeMessage,
+  type PingMessage,
+  type ClientSubscription,
+} from './websocket/index.js';
+
+// Re-export WebSocket config type from loader
+export type { WebSocketConfig } from './loader.js';
+
 // Export the default server for programmatic usage
 export { default } from './server.js';
diff --git a/packages/core/src/loader.ts b/packages/core/src/loader.ts
index 05a35cf..ca25a23 100644
--- a/packages/core/src/loader.ts
+++ b/packages/core/src/loader.ts
@@ -21,6 +21,7 @@ import {
   type WebhookHooksConfig,
   type DefaultWebhookHandlerConfig,
 } from '@/webhooks/index.js';
+import type { ServerOptions as WebSocketServerOptions } from 'ws';
 
 export const pluginTypes = ['core', 'source', 'other'] as const;
 
@@ -155,6 +156,50 @@ export interface RemoteWebhooksConfig {
   trigger?: OutboundWebhookTriggerConfig[];
 }
 
+/**
+ * Configuration for WebSocket server for real-time node change notifications.
+ */
+export interface WebSocketConfig {
+  /**
+   * Whether to enable the WebSocket server.
+   * @default false
+   */
+  enabled?: boolean;
+
+  /**
+   * Port for the WebSocket server. If not specified, WebSocket attaches
+   * to the HTTP server and is accessible at ws://host:httpPort/path.
+   * If specified, WebSocket runs on a separate port: ws://host:wsPort/path.
+   */
+  port?: number;
+
+  /**
+   * Path for WebSocket connections.
+   * @default '/ws'
+   */
+  path?: string;
+
+  /**
+   * Heartbeat interval in milliseconds for keeping connections alive.
+   * @default 30000
+   */
+  heartbeatIntervalMs?: number;
+
+  /**
+   * Advanced pass-through options for the ws.WebSocketServer constructor.
+   * `server`, `port`, and `path` are controlled by UDL and cannot be overridden.
+   *
+   * @example
+   * ```typescript
+   * options: {
+   *   maxPayload: 1024 * 1024, // 1MB
+   *   perMessageDeflate: true,
+   * }
+   * ```
+   */
+  options?: Omit<WebSocketServerOptions, 'server' | 'port' | 'path'>;
+}
+
 /**
  * Configuration for remote data synchronization.
  */
@@ -163,6 +208,21 @@ export interface RemoteConfig {
    * Webhook queue and processing configuration.
    */
   webhooks?: RemoteWebhooksConfig;
+
+  /**
+   * WebSocket server configuration for real-time node change notifications.
+   * When enabled, broadcasts node changes to connected clients immediately.
+   *
+   * @example
+   * ```typescript
+   * websockets: {
+   *   enabled: true,
+   *   path: '/ws',
+   *   heartbeatIntervalMs: 30000,
+   * }
+   * ```
+   */
+  websockets?: WebSocketConfig;
 }
 
 /**
diff --git a/packages/core/src/nodes/actions/createNode.ts b/packages/core/src/nodes/actions/createNode.ts
index 265035d..1fd0d80 100644
--- a/packages/core/src/nodes/actions/createNode.ts
+++ b/packages/core/src/nodes/actions/createNode.ts
@@ -2,6 +2,7 @@ import type { Node } from '@/nodes/types.js';
 import type { NodeStore } from '@/nodes/store.js';
 import { createContentDigest } from '@/nodes/utils/index.js';
 import type { SchemaOption } from '@/schema-builder.js';
+import { emitNodeChange } from '@/nodes/events.js';
 
 /**
  * Input for creating a node - allows partial internal metadata
@@ -147,5 +148,14 @@ export async function createNode(
     store.setTypeSchema(node.internal.type, options.schema);
   }
 
+  // Emit node change event
+  emitNodeChange({
+    type: existingNode ? 'node:updated' : 'node:created',
+    nodeId: node.internal.id,
+    nodeType: node.internal.type,
+    node,
+    timestamp: new Date().toISOString(),
+  });
+
   return node;
 }
diff --git a/packages/core/src/nodes/actions/deleteNode.ts b/packages/core/src/nodes/actions/deleteNode.ts
index 7c773af..a695b70 100644
--- a/packages/core/src/nodes/actions/deleteNode.ts
+++ b/packages/core/src/nodes/actions/deleteNode.ts
@@ -1,6 +1,7 @@
 import type { Node } from '@/nodes/types.js';
 import type { NodeStore } from '@/nodes/store.js';
 import type { DeletionLog } from '@/sync/index.js';
+import { emitNodeChange } from '@/nodes/events.js';
 
 /**
  * Input for deleting a node - accepts either a node object or node ID
@@ -114,6 +115,15 @@ export async function deleteNode(
   // Record deletion before removing from store
   deletionLog?.recordDeletion(node);
 
+  // Emit node deleted event before removing from store
+  emitNodeChange({
+    type: 'node:deleted',
+    nodeId: node.internal.id,
+    nodeType: node.internal.type,
+    node: null,
+    timestamp: new Date().toISOString(),
+  });
+
   // Delete the node from store
   return store.delete(nodeId);
 }
diff --git a/packages/core/src/nodes/actions/extendNode.ts b/packages/core/src/nodes/actions/extendNode.ts
index 11a651a..88bdcd6 100644
--- a/packages/core/src/nodes/actions/extendNode.ts
+++ b/packages/core/src/nodes/actions/extendNode.ts
@@ -1,6 +1,7 @@
 import type { Node } from '@/nodes/types.js';
 import type { NodeStore } from '@/nodes/store.js';
 import { createContentDigest } from '@/nodes/utils/index.js';
+import { emitNodeChange } from '@/nodes/events.js';
 
 /**
  * Data to extend a node with
@@ -98,5 +99,14 @@ export async function extendNode<T extends Node = Node>(
   // Store the updated node
   store.set(extendedNode);
 
+  // Emit node updated event
+  emitNodeChange({
+    type: 'node:updated',
+    nodeId: extendedNode.internal.id,
+    nodeType: extendedNode.internal.type,
+    node: extendedNode,
+    timestamp: new Date().toISOString(),
+  });
+
   return extendedNode as T;
 }
diff --git a/packages/core/src/nodes/events.ts b/packages/core/src/nodes/events.ts
new file mode 100644
index 0000000..ac62e9b
--- /dev/null
+++ b/packages/core/src/nodes/events.ts
@@ -0,0 +1,76 @@
+import { EventEmitter } from 'node:events';
+import type { Node } from './types.js';
+
+/**
+ * Event types emitted when nodes change.
+ */
+export type NodeChangeEventType =
+  | 'node:created'
+  | 'node:updated'
+  | 'node:deleted';
+
+/**
+ * Event payload for node change events.
+ */
+export interface NodeChangeEvent {
+  /** Type of change that occurred */
+  type: NodeChangeEventType;
+  /** ID of the affected node (internal.id) */
+  nodeId: string;
+  /** Type of the affected node (internal.type) */
+  nodeType: string;
+  /** Full node data. Null for deleted events. */
+  node: Node | null;
+  /** ISO 8601 timestamp of when the event occurred */
+  timestamp: string;
+}
+
+/**
+ * Typed event emitter for node changes.
+ */
+export interface NodeEventEmitter {
+  on(
+    event: NodeChangeEventType,
+    listener: (data: NodeChangeEvent) => void
+  ): this;
+  off(
+    event: NodeChangeEventType,
+    listener: (data: NodeChangeEvent) => void
+  ): this;
+  once(
+    event: NodeChangeEventType,
+    listener: (data: NodeChangeEvent) => void
+  ): this;
+  emit(event: NodeChangeEventType, data: NodeChangeEvent): boolean;
+  removeAllListeners(event?: NodeChangeEventType): this;
+}
+
+/**
+ * Internal event emitter instance.
+ */
+const emitter = new EventEmitter() as NodeEventEmitter;
+
+/**
+ * Singleton event emitter for node changes.
+ * Subscribe to node:created, node:updated, node:deleted events.
+ *
+ * @example
+ * ```typescript
+ * import { nodeEvents } from 'universal-data-layer';
+ *
+ * nodeEvents.on('node:created', (event) => {
+ *   console.log(`Node created: ${event.nodeId}`);
+ * });
+ * ```
+ */
+export const nodeEvents: NodeEventEmitter = emitter;
+
+/**
+ * Emit a node change event.
+ * Called internally by node actions (createNode, deleteNode, extendNode).
+ *
+ * @internal
+ */
+export function emitNodeChange(event: NodeChangeEvent): void {
+  emitter.emit(event.type, event);
+}
diff --git a/packages/core/src/nodes/index.ts b/packages/core/src/nodes/index.ts
index 97a679d..60cb5cc 100644
--- a/packages/core/src/nodes/index.ts
+++ b/packages/core/src/nodes/index.ts
@@ -38,6 +38,15 @@ export {
 // Utilities
 export { createNodeId, createContentDigest } from './utils/index.js';
 
+// Events
+export {
+  nodeEvents,
+  emitNodeChange,
+  type NodeChangeEvent,
+  type NodeChangeEventType,
+  type NodeEventEmitter,
+} from './events.js';
+
 // Context for sourceNodes hook
 import type { NodeActions } from './actions/index.js';
 import type { WebhookRegistration } from '@/webhooks/types.js';
diff --git a/packages/core/src/start-server.ts b/packages/core/src/start-server.ts
index 9999270..81fc233 100644
--- a/packages/core/src/start-server.ts
+++ b/packages/core/src/start-server.ts
@@ -20,6 +20,11 @@ import {
   processWebhookBatch,
   OutboundWebhookManager,
 } from '@/webhooks/index.js';
+import {
+  UDLWebSocketServer,
+  setDefaultWebSocketServer,
+  getDefaultWebSocketServer,
+} from '@/websocket/index.js';
 
 export interface StartServerOptions {
   port?: number;
@@ -389,9 +394,18 @@ export async function startServer(options: StartServerOptions = {}) {
 
     // Flush webhook queue before closing server
     console.log('📤 Flushing webhook queue...');
-    void defaultWebhookQueue.flush().then(() => {
+    void defaultWebhookQueue.flush().then(async () => {
       console.log('📤 Webhook queue flushed');
 
+      // Close WebSocket server if running
+      const wsServer = getDefaultWebSocketServer();
+      if (wsServer) {
+        console.log('🔌 Closing WebSocket server...');
+        await wsServer.close();
+        setDefaultWebSocketServer(null);
+        console.log('🔌 WebSocket server closed');
+      }
+
       // Stop accepting new connections and wait for in-flight requests
       server.close(() => {
         console.log('✅ HTTP server closed');
@@ -427,5 +441,18 @@ export async function startServer(options: StartServerOptions = {}) {
     `✨ GraphiQL interface available at http://${host}:${port}/graphiql`
   );
 
+  // Initialize WebSocket server if enabled
+  const wsConfig = userConfig.remote?.websockets;
+  if (wsConfig?.enabled) {
+    const wsServer = new UDLWebSocketServer(server, wsConfig);
+    setDefaultWebSocketServer(wsServer);
+
+    const wsPort = wsConfig.port ?? port;
+    const wsPath = wsConfig.path ?? '/ws';
+    console.log(
+      `🔌 WebSocket server available at ws://${host}:${wsPort}${wsPath}`
+    );
+  }
+
   return { server, config };
 }
diff --git a/packages/core/src/websocket/index.ts b/packages/core/src/websocket/index.ts
new file mode 100644
index 0000000..77518d3
--- /dev/null
+++ b/packages/core/src/websocket/index.ts
@@ -0,0 +1,40 @@
+export {
+  UDLWebSocketServer,
+  type ServerMessage,
+  type NodeChangeMessage,
+  type SubscribedMessage,
+  type PongMessage,
+  type ConnectedMessage,
+  type ClientMessage,
+  type SubscribeMessage,
+  type PingMessage,
+  type ClientSubscription,
+} from './server.js';
+
+import { UDLWebSocketServer } from './server.js';
+
+/**
+ * Singleton WebSocket server instance.
+ * Set via `setDefaultWebSocketServer` during server startup.
+ */
+let _defaultWebSocketServer: UDLWebSocketServer | null = null;
+
+/**
+ * Get the default WebSocket server instance.
+ * Returns null if WebSocket server is not enabled.
+ */
+export function getDefaultWebSocketServer(): UDLWebSocketServer | null {
+  return _defaultWebSocketServer;
+}
+
+/**
+ * Set the default WebSocket server instance.
+ * Called during server startup when WebSocket is enabled.
+ *
+ * @internal
+ */
+export function setDefaultWebSocketServer(
+  server: UDLWebSocketServer | null
+): void {
+  _defaultWebSocketServer = server;
+}
diff --git a/packages/core/src/websocket/server.ts b/packages/core/src/websocket/server.ts
new file mode 100644
index 0000000..99d4011
--- /dev/null
+++ b/packages/core/src/websocket/server.ts
@@ -0,0 +1,297 @@
+import { WebSocketServer, WebSocket, type ServerOptions } from 'ws';
+import type { Server } from 'node:http';
+import { nodeEvents, type NodeChangeEvent } from '@/nodes/events.js';
+import type { WebSocketConfig } from '@/loader.js';
+
+/**
+ * Message types sent from server to client.
+ */
+export type ServerMessage =
+  | NodeChangeMessage
+  | SubscribedMessage
+  | PongMessage
+  | ConnectedMessage;
+
+/**
+ * Node change notification sent to subscribed clients.
+ */
+export interface NodeChangeMessage {
+  type: 'node:created' | 'node:updated' | 'node:deleted';
+  nodeId: string;
+  nodeType: string;
+  timestamp: string;
+  data: unknown | null;
+}
+
+/**
+ * Subscription confirmation message.
+ */
+export interface SubscribedMessage {
+  type: 'subscribed';
+  data: { types: string[] | '*' };
+}
+
+/**
+ * Pong response to client ping.
+ */
+export interface PongMessage {
+  type: 'pong';
+}
+
+/**
+ * Initial connection message.
+ */
+export interface ConnectedMessage {
+  type: 'connected';
+  data: { message: string };
+}
+
+/**
+ * Message types sent from client to server.
+ */
+export type ClientMessage = SubscribeMessage | PingMessage;
+
+/**
+ * Subscribe to specific node types or all types.
+ */
+export interface SubscribeMessage {
+  type: 'subscribe';
+  data: string[] | '*';
+}
+
+/**
+ * Ping message to check connection health.
+ */
+export interface PingMessage {
+  type: 'ping';
+}
+
+/**
+ * Tracks a client's subscription preferences.
+ */
+export interface ClientSubscription {
+  /** Node types to receive updates for. '*' means all types. */
+  types: string[] | '*';
+}
+
+/**
+ * Extended WebSocket with subscription tracking.
+ */
+interface TrackedWebSocket extends WebSocket {
+  isAlive: boolean;
+  subscription: ClientSubscription;
+}
+
+/**
+ * UDL WebSocket server for real-time node change notifications.
+ *
+ * Broadcasts node changes to connected clients in real-time.
+ * Clients can subscribe to specific node types or all types.
+ *
+ * @example
+ * ```typescript
+ * import { UDLWebSocketServer } from 'universal-data-layer';
+ *
+ * const wsServer = new UDLWebSocketServer(httpServer, { path: '/ws' });
+ *
+ * // Server automatically broadcasts node changes
+ * // Clients connect via: ws://localhost:4000/ws
+ * ```
+ */
+export class UDLWebSocketServer {
+  private wss: WebSocketServer;
+  private heartbeatInterval: ReturnType<typeof setInterval> | null = null;
+  private nodeEventHandler: (event: NodeChangeEvent) => void;
+
+  /**
+   * Create a new WebSocket server.
+   *
+   * @param httpServer - HTTP server to attach to (if no port specified)
+   * @param config - WebSocket configuration
+   */
+  constructor(httpServer: Server, config: WebSocketConfig = {}) {
+    const { path = '/ws', heartbeatIntervalMs = 30000, port, options } = config;
+
+    // Build WebSocket server options
+    const wsOptions: ServerOptions = {
+      ...options,
+      path,
+    };
+
+    if (port !== undefined) {
+      // Run on separate port
+      wsOptions.port = port;
+    } else {
+      // Attach to HTTP server
+      wsOptions.server = httpServer;
+    }
+
+    this.wss = new WebSocketServer(wsOptions);
+
+    // Handle new connections
+    this.wss.on('connection', (ws: WebSocket) => {
+      this.handleConnection(ws as TrackedWebSocket);
+    });
+
+    // Set up heartbeat to keep connections alive
+    this.heartbeatInterval = setInterval(() => {
+      this.wss.clients.forEach((ws) => {
+        const trackedWs = ws as TrackedWebSocket;
+        if (!trackedWs.isAlive) {
+          // Connection is dead, terminate it
+          return trackedWs.terminate();
+        }
+        trackedWs.isAlive = false;
+        trackedWs.ping();
+      });
+    }, heartbeatIntervalMs);
+
+    // Clean up heartbeat on server close
+    this.wss.on('close', () => {
+      if (this.heartbeatInterval) {
+        clearInterval(this.heartbeatInterval);
+        this.heartbeatInterval = null;
+      }
+    });
+
+    // Subscribe to node events
+    this.nodeEventHandler = (event: NodeChangeEvent) => {
+      this.broadcastNodeChange(event);
+    };
+    nodeEvents.on('node:created', this.nodeEventHandler);
+    nodeEvents.on('node:updated', this.nodeEventHandler);
+    nodeEvents.on('node:deleted', this.nodeEventHandler);
+  }
+
+  /**
+   * Handle a new WebSocket connection.
+   */
+  private handleConnection(ws: TrackedWebSocket): void {
+    // Initialize tracking
+    ws.isAlive = true;
+    ws.subscription = { types: '*' }; // Default: subscribe to all types
+
+    // Handle pong responses (for heartbeat)
+    ws.on('pong', () => {
+      ws.isAlive = true;
+    });
+
+    // Handle incoming messages
+    ws.on('message', (data: Buffer) => {
+      this.handleMessage(ws, data);
+    });
+
+    // Send connected message
+    this.send(ws, {
+      type: 'connected',
+      data: { message: 'Connected to UDL WebSocket server' },
+    });
+  }
+
+  /**
+   * Handle an incoming message from a client.
+   */
+  private handleMessage(ws: TrackedWebSocket, data: Buffer): void {
+    try {
+      const message = JSON.parse(data.toString()) as ClientMessage;
+
+      switch (message.type) {
+        case 'subscribe':
+          this.handleSubscribe(ws, message);
+          break;
+        case 'ping':
+          this.send(ws, { type: 'pong' });
+          break;
+        default:
+          // Unknown message type, ignore
+          break;
+      }
+    } catch {
+      // Invalid JSON, ignore
+    }
+  }
+
+  /**
+   * Handle a subscribe message from a client.
+   */
+  private handleSubscribe(
+    ws: TrackedWebSocket,
+    message: SubscribeMessage
+  ): void {
+    ws.subscription.types = message.data;
+    this.send(ws, {
+      type: 'subscribed',
+      data: { types: message.data },
+    });
+  }
+
+  /**
+   * Broadcast a node change event to all subscribed clients.
+   */
+  private broadcastNodeChange(event: NodeChangeEvent): void {
+    const message: NodeChangeMessage = {
+      type: event.type,
+      nodeId: event.nodeId,
+      nodeType: event.nodeType,
+      timestamp: event.timestamp,
+      data: event.node,
+    };
+
+    this.wss.clients.forEach((ws) => {
+      const trackedWs = ws as TrackedWebSocket;
+      if (trackedWs.readyState !== WebSocket.OPEN) {
+        return;
+      }
+
+      // Check if client is subscribed to this node type
+      const { types } = trackedWs.subscription;
+      if (types === '*' || types.includes(event.nodeType)) {
+        this.send(trackedWs, message);
+      }
+    });
+  }
+
+  /**
+   * Send a message to a WebSocket client.
+   */
+  private send(ws: WebSocket, message: ServerMessage): void {
+    if (ws.readyState === WebSocket.OPEN) {
+      ws.send(JSON.stringify(message));
+    }
+  }
+
+  /**
+   * Get the number of connected clients.
+   */
+  getClientCount(): number {
+    return this.wss.clients.size;
+  }
+
+  /**
+   * Close the WebSocket server and clean up resources.
+   */
+  close(): Promise<void> {
+    return new Promise((resolve) => {
+      // Unsubscribe from node events
+      nodeEvents.off('node:created', this.nodeEventHandler);
+      nodeEvents.off('node:updated', this.nodeEventHandler);
+      nodeEvents.off('node:deleted', this.nodeEventHandler);
+
+      // Clear heartbeat interval
+      if (this.heartbeatInterval) {
+        clearInterval(this.heartbeatInterval);
+        this.heartbeatInterval = null;
+      }
+
+      // Close all client connections
+      this.wss.clients.forEach((ws) => {
+        ws.close();
+      });
+
+      // Close the server
+      this.wss.close(() => {
+        resolve();
+      });
+    });
+  }
+}
diff --git a/packages/core/tests/integration/websocket.test.ts b/packages/core/tests/integration/websocket.test.ts
new file mode 100644
index 0000000..31f3cac
--- /dev/null
+++ b/packages/core/tests/integration/websocket.test.ts
@@ -0,0 +1,404 @@
+import { describe, it, expect, beforeAll, afterAll, beforeEach } from 'vitest';
+import { createServer, type Server } from 'node:http';
+import WebSocket from 'ws';
+import {
+  UDLWebSocketServer,
+  type ServerMessage,
+  type NodeChangeMessage,
+} from '@/websocket/server.js';
+import { NodeStore } from '@/nodes/store.js';
+import { createNode } from '@/nodes/actions/createNode.js';
+import { deleteNode } from '@/nodes/actions/deleteNode.js';
+import { extendNode } from '@/nodes/actions/extendNode.js';
+
+function waitForMessage(
+  ws: WebSocket,
+  timeoutMs = 5000
+): Promise<ServerMessage> {
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      reject(new Error('Timeout waiting for message'));
+    }, timeoutMs);
+
+    ws.once('message', (data: Buffer) => {
+      clearTimeout(timeout);
+      resolve(JSON.parse(data.toString()) as ServerMessage);
+    });
+  });
+}
+
+describe('WebSocket integration', () => {
+  let httpServer: Server;
+  let wsServer: UDLWebSocketServer;
+  let store: NodeStore;
+  let serverPort: number;
+  let client: WebSocket | null = null;
+
+  beforeAll(async () => {
+    // Create HTTP server
+    httpServer = createServer();
+    await new Promise<void>((resolve) => {
+      httpServer.listen(0, () => {
+        const address = httpServer.address();
+        serverPort =
+          typeof address === 'object' && address ? address.port : 4000;
+        resolve();
+      });
+    });
+
+    // Create WebSocket server
+    wsServer = new UDLWebSocketServer(httpServer, {
+      path: '/ws',
+      heartbeatIntervalMs: 60000,
+    });
+  });
+
+  afterAll(async () => {
+    await wsServer.close();
+    await new Promise<void>((resolve) => {
+      httpServer.close(() => resolve());
+    });
+  });
+
+  beforeEach(() => {
+    store = new NodeStore();
+    if (client && client.readyState === WebSocket.OPEN) {
+      client.close();
+      client = null;
+    }
+  });
+
+  describe('createNode integration', () => {
+    it('broadcasts node:created when creating a new node', async () => {
+      client = new WebSocket(`ws://localhost:${serverPort}/ws`);
+      await waitForMessage(client); // connected message
+
+      // Create a node using the action
+      await createNode(
+        {
+          internal: {
+            id: 'product-1',
+            type: 'Product',
+            owner: 'test-plugin',
+          },
+          name: 'Test Product',
+          price: 99.99,
+        },
+        { store }
+      );
+
+      const message = (await waitForMessage(client)) as NodeChangeMessage;
+
+      expect(message.type).toBe('node:created');
+      expect(message.nodeId).toBe('product-1');
+      expect(message.nodeType).toBe('Product');
+      expect(message.data).toMatchObject({
+        internal: {
+          id: 'product-1',
+          type: 'Product',
+        },
+        name: 'Test Product',
+        price: 99.99,
+      });
+    });
+
+    it('broadcasts node:updated when updating an existing node', async () => {
+      // Create initial node
+      await createNode(
+        {
+          internal: {
+            id: 'product-1',
+            type: 'Product',
+            owner: 'test-plugin',
+          },
+          name: 'Original Name',
+        },
+        { store }
+      );
+
+      client = new WebSocket(`ws://localhost:${serverPort}/ws`);
+      await waitForMessage(client); // connected message
+
+      // Update the node
+      await createNode(
+        {
+          internal: {
+            id: 'product-1',
+            type: 'Product',
+            owner: 'test-plugin',
+          },
+          name: 'Updated Name',
+        },
+        { store }
+      );
+
+      const message = (await waitForMessage(client)) as NodeChangeMessage;
+
+      expect(message.type).toBe('node:updated');
+      expect(message.nodeId).toBe('product-1');
+      expect((message.data as { name: string }).name).toBe('Updated Name');
+    });
+  });
+
+  describe('deleteNode integration', () => {
+    it('broadcasts node:deleted when deleting a node', async () => {
+      // Create a node first
+      await createNode(
+        {
+          internal: {
+            id: 'product-1',
+            type: 'Product',
+            owner: 'test-plugin',
+          },
+          name: 'Test Product',
+        },
+        { store }
+      );
+
+      client = new WebSocket(`ws://localhost:${serverPort}/ws`);
+      await waitForMessage(client); // connected message
+
+      // Delete the node
+      await deleteNode('product-1', { store });
+
+      const message = (await waitForMessage(client)) as NodeChangeMessage;
+
+      expect(message.type).toBe('node:deleted');
+      expect(message.nodeId).toBe('product-1');
+      expect(message.nodeType).toBe('Product');
+      expect(message.data).toBeNull();
+    });
+  });
+
+  describe('extendNode integration', () => {
+    it('broadcasts node:updated when extending a node', async () => {
+      // Create a node first
+      await createNode(
+        {
+          internal: {
+            id: 'product-1',
+            type: 'Product',
+            owner: 'test-plugin',
+          },
+          name: 'Test Product',
+        },
+        { store }
+      );
+
+      client = new WebSocket(`ws://localhost:${serverPort}/ws`);
+      await waitForMessage(client); // connected message
+      // We also receive node:created from createNode above before we connected,
+      // but since we connected after, we won't receive it.
+      // Actually, since the createNode happened before websocket connection,
+      // the event was emitted but no client was connected yet.
+
+      // Extend the node
+      await extendNode(
+        'product-1',
+        { featured: true, discount: 10 },
+        { store }
+      );
+
+      const message = (await waitForMessage(client)) as NodeChangeMessage;
+
+      expect(message.type).toBe('node:updated');
+      expect(message.nodeId).toBe('product-1');
+      expect(message.data).toMatchObject({
+        name: 'Test Product',
+        featured: true,
+        discount: 10,
+      });
+    });
+  });
+
+  describe('subscription filtering integration', () => {
+    it('only receives events for subscribed types', async () => {
+      client = new WebSocket(`ws://localhost:${serverPort}/ws`);
+      await waitForMessage(client); // connected message
+
+      // Subscribe to only Product types
+      client.send(JSON.stringify({ type: 'subscribe', data: ['Product'] }));
+      await waitForMessage(client); // subscribed message
+
+      // Create a Collection - should NOT trigger event for this client
+      await createNode(
+        {
+          internal: {
+            id: 'collection-1',
+            type: 'Collection',
+            owner: 'test-plugin',
+          },
+          name: 'Test Collection',
+        },
+        { store }
+      );
+
+      // Create a Product - SHOULD trigger event
+      await createNode(
+        {
+          internal: {
+            id: 'product-1',
+            type: 'Product',
+            owner: 'test-plugin',
+          },
+          name: 'Test Product',
+        },
+        { store }
+      );
+
+      const message = (await waitForMessage(client)) as NodeChangeMessage;
+
+      // Should receive Product, not Collection
+      expect(message.type).toBe('node:created');
+      expect(message.nodeType).toBe('Product');
+      expect(message.nodeId).toBe('product-1');
+    });
+
+    it('receives all events when subscribed to *', async () => {
+      client = new WebSocket(`ws://localhost:${serverPort}/ws`);
+      await waitForMessage(client); // connected message
+
+      // Default is *, but let's be explicit
+      client.send(JSON.stringify({ type: 'subscribe', data: '*' }));
+      await waitForMessage(client); // subscribed message
+
+      // Collect received messages
+      const receivedMessages: NodeChangeMessage[] = [];
+      const messagePromise = new Promise<void>((resolve) => {
+        const handler = (data: Buffer) => {
+          const msg = JSON.parse(data.toString()) as ServerMessage;
+          if (msg.type === 'node:created') {
+            receivedMessages.push(msg as NodeChangeMessage);
+            if (receivedMessages.length === 2) {
+              client!.off('message', handler);
+              resolve();
+            }
+          }
+        };
+        client!.on('message', handler);
+      });
+
+      // Create different node types
+      await createNode(
+        {
+          internal: {
+            id: 'product-1',
+            type: 'Product',
+            owner: 'test-plugin',
+          },
+          name: 'Test Product',
+        },
+        { store }
+      );
+
+      await createNode(
+        {
+          internal: {
+            id: 'collection-1',
+            type: 'Collection',
+            owner: 'test-plugin',
+          },
+          name: 'Test Collection',
+        },
+        { store }
+      );
+
+      await messagePromise;
+
+      const types = receivedMessages.map((m) => m.nodeType).sort();
+      expect(types).toEqual(['Collection', 'Product']);
+    });
+  });
+
+  describe('multiple clients integration', () => {
+    it('broadcasts to multiple clients with different subscriptions', async () => {
+      // Client 1: Subscribe to Product
+      const client1 = new WebSocket(`ws://localhost:${serverPort}/ws`);
+      await waitForMessage(client1); // connected
+      client1.send(JSON.stringify({ type: 'subscribe', data: ['Product'] }));
+      await waitForMessage(client1); // subscribed
+
+      // Client 2: Subscribe to Collection
+      const client2 = new WebSocket(`ws://localhost:${serverPort}/ws`);
+      await waitForMessage(client2); // connected
+      client2.send(JSON.stringify({ type: 'subscribe', data: ['Collection'] }));
+      await waitForMessage(client2); // subscribed
+
+      try {
+        // Set up message collectors BEFORE creating nodes to avoid race conditions
+        const client1Messages: NodeChangeMessage[] = [];
+        const client2Messages: NodeChangeMessage[] = [];
+
+        const client1Promise = new Promise<void>((resolve) => {
+          const handler = (data: Buffer) => {
+            const msg = JSON.parse(data.toString()) as ServerMessage;
+            if (
+              msg.type === 'node:created' &&
+              (msg as NodeChangeMessage).nodeType === 'Product'
+            ) {
+              client1Messages.push(msg as NodeChangeMessage);
+              client1.off('message', handler);
+              resolve();
+            }
+          };
+          client1.on('message', handler);
+        });
+
+        const client2Promise = new Promise<void>((resolve) => {
+          const handler = (data: Buffer) => {
+            const msg = JSON.parse(data.toString()) as ServerMessage;
+            if (
+              msg.type === 'node:created' &&
+              (msg as NodeChangeMessage).nodeType === 'Collection'
+            ) {
+              client2Messages.push(msg as NodeChangeMessage);
+              client2.off('message', handler);
+              resolve();
+            }
+          };
+          client2.on('message', handler);
+        });
+
+        // Create a Product
+        await createNode(
+          {
+            internal: {
+              id: 'product-1',
+              type: 'Product',
+              owner: 'test-plugin',
+            },
+            name: 'Test Product',
+          },
+          { store }
+        );
+
+        // Create a Collection
+        await createNode(
+          {
+            internal: {
+              id: 'collection-1',
+              type: 'Collection',
+              owner: 'test-plugin',
+            },
+            name: 'Test Collection',
+          },
+          { store }
+        );
+
+        // Wait for both clients to receive their messages
+        await Promise.all([client1Promise, client2Promise]);
+
+        // Client 1 should only receive Product
+        expect(client1Messages).toHaveLength(1);
+        expect(client1Messages[0].nodeType).toBe('Product');
+
+        // Client 2 should only receive Collection
+        expect(client2Messages).toHaveLength(1);
+        expect(client2Messages[0].nodeType).toBe('Collection');
+      } finally {
+        client1.close();
+        client2.close();
+      }
+    });
+  });
+});
diff --git a/packages/core/tests/unit/nodes/events.test.ts b/packages/core/tests/unit/nodes/events.test.ts
new file mode 100644
index 0000000..e6be002
--- /dev/null
+++ b/packages/core/tests/unit/nodes/events.test.ts
@@ -0,0 +1,215 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import {
+  nodeEvents,
+  emitNodeChange,
+  type NodeChangeEvent,
+} from '@/nodes/events.js';
+import type { Node } from '@/nodes/types.js';
+
+function createMockNode(overrides: Partial<Node['internal']> = {}): Node {
+  return {
+    internal: {
+      id: 'node-1',
+      type: 'TestNode',
+      owner: 'test-plugin',
+      contentDigest: 'digest123',
+      createdAt: Date.now(),
+      modifiedAt: Date.now(),
+      ...overrides,
+    },
+    name: 'Test Node',
+  } as Node;
+}
+
+describe('nodeEvents', () => {
+  let listeners: Array<(event: NodeChangeEvent) => void> = [];
+
+  afterEach(() => {
+    // Clean up all listeners
+    for (const listener of listeners) {
+      nodeEvents.off('node:created', listener);
+      nodeEvents.off('node:updated', listener);
+      nodeEvents.off('node:deleted', listener);
+    }
+    listeners = [];
+  });
+
+  describe('emitNodeChange', () => {
+    it('emits node:created events', () => {
+      const handler = vi.fn();
+      listeners.push(handler);
+      nodeEvents.on('node:created', handler);
+
+      const node = createMockNode({ id: 'product-1', type: 'Product' });
+      const event: NodeChangeEvent = {
+        type: 'node:created',
+        nodeId: 'product-1',
+        nodeType: 'Product',
+        node,
+        timestamp: '2024-06-15T12:00:00.000Z',
+      };
+
+      emitNodeChange(event);
+
+      expect(handler).toHaveBeenCalledOnce();
+      expect(handler).toHaveBeenCalledWith(event);
+    });
+
+    it('emits node:updated events', () => {
+      const handler = vi.fn();
+      listeners.push(handler);
+      nodeEvents.on('node:updated', handler);
+
+      const node = createMockNode({ id: 'product-1', type: 'Product' });
+      const event: NodeChangeEvent = {
+        type: 'node:updated',
+        nodeId: 'product-1',
+        nodeType: 'Product',
+        node,
+        timestamp: '2024-06-15T12:00:00.000Z',
+      };
+
+      emitNodeChange(event);
+
+      expect(handler).toHaveBeenCalledOnce();
+      expect(handler).toHaveBeenCalledWith(event);
+    });
+
+    it('emits node:deleted events with null node', () => {
+      const handler = vi.fn();
+      listeners.push(handler);
+      nodeEvents.on('node:deleted', handler);
+
+      const event: NodeChangeEvent = {
+        type: 'node:deleted',
+        nodeId: 'product-1',
+        nodeType: 'Product',
+        node: null,
+        timestamp: '2024-06-15T12:00:00.000Z',
+      };
+
+      emitNodeChange(event);
+
+      expect(handler).toHaveBeenCalledOnce();
+      expect(handler).toHaveBeenCalledWith(event);
+    });
+
+    it('only emits to listeners of the specific event type', () => {
+      const createdHandler = vi.fn();
+      const updatedHandler = vi.fn();
+      const deletedHandler = vi.fn();
+
+      listeners.push(createdHandler, updatedHandler, deletedHandler);
+      nodeEvents.on('node:created', createdHandler);
+      nodeEvents.on('node:updated', updatedHandler);
+      nodeEvents.on('node:deleted', deletedHandler);
+
+      const node = createMockNode();
+      emitNodeChange({
+        type: 'node:updated',
+        nodeId: 'node-1',
+        nodeType: 'TestNode',
+        node,
+        timestamp: '2024-06-15T12:00:00.000Z',
+      });
+
+      expect(createdHandler).not.toHaveBeenCalled();
+      expect(updatedHandler).toHaveBeenCalledOnce();
+      expect(deletedHandler).not.toHaveBeenCalled();
+    });
+
+    it('supports multiple listeners for the same event', () => {
+      const handler1 = vi.fn();
+      const handler2 = vi.fn();
+
+      listeners.push(handler1, handler2);
+      nodeEvents.on('node:created', handler1);
+      nodeEvents.on('node:created', handler2);
+
+      const node = createMockNode();
+      emitNodeChange({
+        type: 'node:created',
+        nodeId: 'node-1',
+        nodeType: 'TestNode',
+        node,
+        timestamp: '2024-06-15T12:00:00.000Z',
+      });
+
+      expect(handler1).toHaveBeenCalledOnce();
+      expect(handler2).toHaveBeenCalledOnce();
+    });
+  });
+
+  describe('nodeEvents.off', () => {
+    it('removes a listener', () => {
+      const handler = vi.fn();
+      listeners.push(handler);
+      nodeEvents.on('node:created', handler);
+
+      // Remove the listener
+      nodeEvents.off('node:created', handler);
+
+      emitNodeChange({
+        type: 'node:created',
+        nodeId: 'node-1',
+        nodeType: 'TestNode',
+        node: createMockNode(),
+        timestamp: '2024-06-15T12:00:00.000Z',
+      });
+
+      expect(handler).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('nodeEvents.once', () => {
+    it('listener is called only once', () => {
+      const handler = vi.fn();
+      nodeEvents.once('node:created', handler);
+
+      const node = createMockNode();
+      emitNodeChange({
+        type: 'node:created',
+        nodeId: 'node-1',
+        nodeType: 'TestNode',
+        node,
+        timestamp: '2024-06-15T12:00:00.000Z',
+      });
+
+      emitNodeChange({
+        type: 'node:created',
+        nodeId: 'node-2',
+        nodeType: 'TestNode',
+        node,
+        timestamp: '2024-06-15T12:00:00.000Z',
+      });
+
+      expect(handler).toHaveBeenCalledOnce();
+    });
+  });
+
+  describe('event payload', () => {
+    it('includes all required fields', () => {
+      const handler = vi.fn();
+      listeners.push(handler);
+      nodeEvents.on('node:created', handler);
+
+      const node = createMockNode({ id: 'test-123', type: 'Product' });
+      const timestamp = '2024-06-15T12:00:00.000Z';
+
+      emitNodeChange({
+        type: 'node:created',
+        nodeId: 'test-123',
+        nodeType: 'Product',
+        node,
+        timestamp,
+      });
+
+      const receivedEvent = handler.mock.calls[0][0] as NodeChangeEvent;
+      expect(receivedEvent.type).toBe('node:created');
+      expect(receivedEvent.nodeId).toBe('test-123');
+      expect(receivedEvent.nodeType).toBe('Product');
+      expect(receivedEvent.node).toBe(node);
+      expect(receivedEvent.timestamp).toBe(timestamp);
+    });
+  });
+});
diff --git a/packages/core/tests/unit/websocket/server.test.ts b/packages/core/tests/unit/websocket/server.test.ts
new file mode 100644
index 0000000..7567b27
--- /dev/null
+++ b/packages/core/tests/unit/websocket/server.test.ts
@@ -0,0 +1,376 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { createServer, type Server } from 'node:http';
+import WebSocket from 'ws';
+import {
+  UDLWebSocketServer,
+  type ServerMessage,
+  type NodeChangeMessage,
+} from '@/websocket/server.js';
+import { emitNodeChange } from '@/nodes/events.js';
+import type { Node } from '@/nodes/types.js';
+
+function createMockNode(overrides: Partial<Node['internal']> = {}): Node {
+  return {
+    internal: {
+      id: 'node-1',
+      type: 'TestNode',
+      owner: 'test-plugin',
+      contentDigest: 'digest123',
+      createdAt: Date.now(),
+      modifiedAt: Date.now(),
+      ...overrides,
+    },
+    name: 'Test Node',
+  } as Node;
+}
+
+function waitForMessage(ws: WebSocket): Promise<ServerMessage> {
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      reject(new Error('Timeout waiting for message'));
+    }, 5000);
+
+    ws.once('message', (data: Buffer) => {
+      clearTimeout(timeout);
+      resolve(JSON.parse(data.toString()) as ServerMessage);
+    });
+  });
+}
+
+function waitForOpen(ws: WebSocket): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (ws.readyState === WebSocket.OPEN) {
+      resolve();
+      return;
+    }
+    ws.once('open', () => resolve());
+    ws.once('error', reject);
+  });
+}
+
+describe('UDLWebSocketServer', () => {
+  let httpServer: Server;
+  let wsServer: UDLWebSocketServer;
+  let client: WebSocket | null = null;
+  let serverPort: number;
+
+  beforeEach(async () => {
+    // Create HTTP server
+    httpServer = createServer();
+    await new Promise<void>((resolve) => {
+      httpServer.listen(0, () => {
+        const address = httpServer.address();
+        serverPort =
+          typeof address === 'object' && address ? address.port : 4000;
+        resolve();
+      });
+    });
+
+    // Create WebSocket server
+    wsServer = new UDLWebSocketServer(httpServer, {
+      path: '/ws',
+      heartbeatIntervalMs: 60000, // Long interval to avoid interference in tests
+    });
+  });
+
+  afterEach(async () => {
+    // Close client if connected
+    if (client && client.readyState === WebSocket.OPEN) {
+      client.close();
+      client = null;
+    }
+
+    // Close servers
+    await wsServer.close();
+    await new Promise<void>((resolve) => {
+      httpServer.close(() => resolve());
+    });
+  });
+
+  describe('connection handling', () => {
+    it('accepts WebSocket connections', async () => {
+      client = new WebSocket(`ws://localhost:${serverPort}/ws`);
+      await waitForOpen(client);
+
+      expect(client.readyState).toBe(WebSocket.OPEN);
+    });
+
+    it('sends connected message on connection', async () => {
+      client = new WebSocket(`ws://localhost:${serverPort}/ws`);
+      const message = await waitForMessage(client);
+
+      expect(message.type).toBe('connected');
+      expect(
+        (message as { type: string; data: { message: string } }).data.message
+      ).toContain('Connected');
+    });
+
+    it('defaults subscription to all types (*)', async () => {
+      client = new WebSocket(`ws://localhost:${serverPort}/ws`);
+      await waitForMessage(client); // connected message
+
+      // Emit a node change - should be received since default is *
+      const node = createMockNode({ id: 'product-1', type: 'Product' });
+      emitNodeChange({
+        type: 'node:created',
+        nodeId: 'product-1',
+        nodeType: 'Product',
+        node,
+        timestamp: '2024-06-15T12:00:00.000Z',
+      });
+
+      const message = await waitForMessage(client);
+      expect(message.type).toBe('node:created');
+    });
+
+    it('tracks client count', async () => {
+      expect(wsServer.getClientCount()).toBe(0);
+
+      client = new WebSocket(`ws://localhost:${serverPort}/ws`);
+      await waitForOpen(client);
+
+      expect(wsServer.getClientCount()).toBe(1);
+
+      // Connect second client
+      const client2 = new WebSocket(`ws://localhost:${serverPort}/ws`);
+      await waitForOpen(client2);
+
+      expect(wsServer.getClientCount()).toBe(2);
+
+      // Close second client
+      client2.close();
+      await new Promise((resolve) => setTimeout(resolve, 100));
+
+      expect(wsServer.getClientCount()).toBe(1);
+    });
+  });
+
+  describe('message handling', () => {
+    it('responds to ping with pong', async () => {
+      client = new WebSocket(`ws://localhost:${serverPort}/ws`);
+      await waitForMessage(client); // connected message
+
+      client.send(JSON.stringify({ type: 'ping' }));
+      const message = await waitForMessage(client);
+
+      expect(message.type).toBe('pong');
+    });
+
+    it('handles subscribe message', async () => {
+      client = new WebSocket(`ws://localhost:${serverPort}/ws`);
+      await waitForMessage(client); // connected message
+
+      client.send(JSON.stringify({ type: 'subscribe', data: ['Product'] }));
+      const message = await waitForMessage(client);
+
+      expect(message.type).toBe('subscribed');
+      expect(
+        (message as { type: string; data: { types: string[] } }).data.types
+      ).toEqual(['Product']);
+    });
+
+    it('handles subscribe to all (*)', async () => {
+      client = new WebSocket(`ws://localhost:${serverPort}/ws`);
+      await waitForMessage(client); // connected message
+
+      client.send(JSON.stringify({ type: 'subscribe', data: '*' }));
+      const message = await waitForMessage(client);
+
+      expect(message.type).toBe('subscribed');
+      expect(
+        (message as { type: string; data: { types: string } }).data.types
+      ).toBe('*');
+    });
+
+    it('ignores invalid JSON', async () => {
+      client = new WebSocket(`ws://localhost:${serverPort}/ws`);
+      await waitForMessage(client); // connected message
+
+      // Send invalid JSON - should not crash
+      client.send('not valid json');
+
+      // Should still respond to valid messages
+      client.send(JSON.stringify({ type: 'ping' }));
+      const message = await waitForMessage(client);
+
+      expect(message.type).toBe('pong');
+    });
+
+    it('ignores unknown message types', async () => {
+      client = new WebSocket(`ws://localhost:${serverPort}/ws`);
+      await waitForMessage(client); // connected message
+
+      // Send unknown message type
+      client.send(JSON.stringify({ type: 'unknown' }));
+
+      // Should still respond to valid messages
+      client.send(JSON.stringify({ type: 'ping' }));
+      const message = await waitForMessage(client);
+
+      expect(message.type).toBe('pong');
+    });
+  });
+
+  describe('broadcasting', () => {
+    it('broadcasts node:created events', async () => {
+      client = new WebSocket(`ws://localhost:${serverPort}/ws`);
+      await waitForMessage(client); // connected message
+
+      const node = createMockNode({ id: 'product-1', type: 'Product' });
+      emitNodeChange({
+        type: 'node:created',
+        nodeId: 'product-1',
+        nodeType: 'Product',
+        node,
+        timestamp: '2024-06-15T12:00:00.000Z',
+      });
+
+      const message = (await waitForMessage(client)) as NodeChangeMessage;
+
+      expect(message.type).toBe('node:created');
+      expect(message.nodeId).toBe('product-1');
+      expect(message.nodeType).toBe('Product');
+      expect(message.data).toEqual(node);
+      expect(message.timestamp).toBe('2024-06-15T12:00:00.000Z');
+    });
+
+    it('broadcasts node:updated events', async () => {
+      client = new WebSocket(`ws://localhost:${serverPort}/ws`);
+      await waitForMessage(client); // connected message
+
+      const node = createMockNode({ id: 'product-1', type: 'Product' });
+      emitNodeChange({
+        type: 'node:updated',
+        nodeId: 'product-1',
+        nodeType: 'Product',
+        node,
+        timestamp: '2024-06-15T12:00:00.000Z',
+      });
+
+      const message = (await waitForMessage(client)) as NodeChangeMessage;
+
+      expect(message.type).toBe('node:updated');
+      expect(message.nodeId).toBe('product-1');
+      expect(message.data).toEqual(node);
+    });
+
+    it('broadcasts node:deleted events with null data', async () => {
+      client = new WebSocket(`ws://localhost:${serverPort}/ws`);
+      await waitForMessage(client); // connected message
+
+      emitNodeChange({
+        type: 'node:deleted',
+        nodeId: 'product-1',
+        nodeType: 'Product',
+        node: null,
+        timestamp: '2024-06-15T12:00:00.000Z',
+      });
+
+      const message = (await waitForMessage(client)) as NodeChangeMessage;
+
+      expect(message.type).toBe('node:deleted');
+      expect(message.nodeId).toBe('product-1');
+      expect(message.data).toBeNull();
+    });
+
+    it('filters broadcasts by subscription', async () => {
+      client = new WebSocket(`ws://localhost:${serverPort}/ws`);
+      await waitForMessage(client); // connected message
+
+      // Subscribe to only Product types
+      client.send(JSON.stringify({ type: 'subscribe', data: ['Product'] }));
+      await waitForMessage(client); // subscribed message
+
+      // Emit a Collection event - should NOT be received
+      emitNodeChange({
+        type: 'node:created',
+        nodeId: 'collection-1',
+        nodeType: 'Collection',
+        node: createMockNode({ id: 'collection-1', type: 'Collection' }),
+        timestamp: '2024-06-15T12:00:00.000Z',
+      });
+
+      // Emit a Product event - SHOULD be received
+      const productNode = createMockNode({ id: 'product-1', type: 'Product' });
+      emitNodeChange({
+        type: 'node:created',
+        nodeId: 'product-1',
+        nodeType: 'Product',
+        node: productNode,
+        timestamp: '2024-06-15T12:00:00.000Z',
+      });
+
+      const message = (await waitForMessage(client)) as NodeChangeMessage;
+
+      // Should receive Product, not Collection
+      expect(message.nodeType).toBe('Product');
+      expect(message.nodeId).toBe('product-1');
+    });
+
+    it('broadcasts to multiple clients', async () => {
+      client = new WebSocket(`ws://localhost:${serverPort}/ws`);
+      await waitForMessage(client); // connected message
+
+      const client2 = new WebSocket(`ws://localhost:${serverPort}/ws`);
+      await waitForMessage(client2); // connected message
+
+      try {
+        const node = createMockNode({ id: 'product-1', type: 'Product' });
+        emitNodeChange({
+          type: 'node:created',
+          nodeId: 'product-1',
+          nodeType: 'Product',
+          node,
+          timestamp: '2024-06-15T12:00:00.000Z',
+        });
+
+        const [message1, message2] = await Promise.all([
+          waitForMessage(client),
+          waitForMessage(client2),
+        ]);
+
+        expect(message1.type).toBe('node:created');
+        expect(message2.type).toBe('node:created');
+      } finally {
+        client2.close();
+      }
+    });
+  });
+
+  describe('close', () => {
+    it('closes all client connections', async () => {
+      client = new WebSocket(`ws://localhost:${serverPort}/ws`);
+      await waitForOpen(client);
+
+      // Set up close listener before calling close to avoid race condition
+      const closePromise = new Promise<void>((resolve) => {
+        client!.once('close', () => resolve());
+        // Also resolve if already closed
+        if (client!.readyState === WebSocket.CLOSED) {
+          resolve();
+        }
+      });
+
+      await wsServer.close();
+      await closePromise;
+
+      expect(client.readyState).toBe(WebSocket.CLOSED);
+    });
+
+    it('stops listening for node events after close', async () => {
+      client = new WebSocket(`ws://localhost:${serverPort}/ws`);
+      await waitForMessage(client); // connected message
+
+      await wsServer.close();
+
+      // Reconnect to test - need new server
+      wsServer = new UDLWebSocketServer(httpServer, { path: '/ws' });
+      const client2 = new WebSocket(`ws://localhost:${serverPort}/ws`);
+      await waitForMessage(client2); // connected message
+
+      // Original server should not broadcast
+      // (we can't easily test this, but the close() unsubscribes from events)
+      client2.close();
+    });
+  });
+});

From e13f56d411a38ae9ec5ac0894f1bac09acc1647c Mon Sep 17 00:00:00 2001
From: dawidurbanski <hi@dawidurbanski.com>
Date: Mon, 22 Dec 2025 18:51:22 +0100
Subject: [PATCH 21/46] chore: add changesets for recent features

Add changeset documentation for:
- WebSocket server for real-time node change notifications
- Sync query API for partial updates
- Default webhook handler for standardized CRUD operations
---
 .changeset/default-webhook-handler.md | 75 +++++++++++++++++++++++++++
 .changeset/sync-query-api.md          | 51 ++++++++++++++++++
 .changeset/websocket-server.md        | 53 +++++++++++++++++++
 3 files changed, 179 insertions(+)
 create mode 100644 .changeset/default-webhook-handler.md
 create mode 100644 .changeset/sync-query-api.md
 create mode 100644 .changeset/websocket-server.md

diff --git a/.changeset/default-webhook-handler.md b/.changeset/default-webhook-handler.md
new file mode 100644
index 0000000..bb2e4e9
--- /dev/null
+++ b/.changeset/default-webhook-handler.md
@@ -0,0 +1,75 @@
+---
+'universal-data-layer': minor
+---
+
+Add default webhook handler for standardized CRUD operations
+
+This release introduces a default webhook handler that provides a standardized way to create, update, and delete nodes via webhooks. This eliminates the need for plugins to implement their own webhook handlers for basic CRUD operations.
+
+**Features:**
+
+- Automatic registration of `/sync` webhook endpoint for each loaded plugin
+- Standardized payload format for `create`, `update`, `delete`, and `upsert` operations
+- Support for custom `idField` to look up nodes by external identifiers
+- Configurable per-plugin path overrides or disabling
+- Integration with plugin loading for automatic setup
+
+**Configuration:**
+
+```typescript
+export const { config } = defineConfig({
+  defaultWebhook: {
+    enabled: true,
+    path: 'sync', // Default endpoint path
+    plugins: {
+      // Customize path for specific plugin
+      contentful: { path: 'content-sync' },
+      // Disable for a specific plugin
+      'legacy-plugin': false,
+    },
+  },
+});
+```
+
+**Payload format:**
+
+```typescript
+interface DefaultWebhookPayload {
+  operation: 'create' | 'update' | 'delete' | 'upsert';
+  nodeId: string; // External ID or internal node ID
+  nodeType: string; // Node type (e.g., 'Product', 'Article')
+  data?: Record<string, unknown>; // Node data (required for create/update/upsert)
+}
+```
+
+**Example requests:**
+
+```bash
+# Create a node
+curl -X POST http://localhost:4000/_webhooks/my-plugin/sync \
+  -H "Content-Type: application/json" \
+  -d '{"operation":"create","nodeId":"123","nodeType":"Product","data":{"name":"Widget"}}'
+
+# Update a node
+curl -X POST http://localhost:4000/_webhooks/my-plugin/sync \
+  -d '{"operation":"update","nodeId":"123","nodeType":"Product","data":{"name":"Updated Widget"}}'
+
+# Delete a node
+curl -X POST http://localhost:4000/_webhooks/my-plugin/sync \
+  -d '{"operation":"delete","nodeId":"123","nodeType":"Product"}'
+
+# Upsert (create or update)
+curl -X POST http://localhost:4000/_webhooks/my-plugin/sync \
+  -d '{"operation":"upsert","nodeId":"123","nodeType":"Product","data":{"name":"Widget"}}'
+```
+
+**idField support:**
+
+When a plugin specifies an `idField` in its config, the default webhook handler can look up existing nodes by that field:
+
+```typescript
+// Plugin config
+export const config = defineConfig({
+  idField: 'externalId', // Webhook will look up nodes by this field
+});
+```
diff --git a/.changeset/sync-query-api.md b/.changeset/sync-query-api.md
new file mode 100644
index 0000000..a61e0cf
--- /dev/null
+++ b/.changeset/sync-query-api.md
@@ -0,0 +1,51 @@
+---
+'universal-data-layer': minor
+---
+
+Add sync query API for partial updates
+
+This release introduces a `GET /_sync` endpoint that enables clients to fetch only the nodes that have changed since their last sync. This enables efficient incremental synchronization without requiring a full data refetch.
+
+**Features:**
+
+- `GET /_sync?since={timestamp}` endpoint for querying changes
+- Returns updated nodes and deleted node IDs since the given timestamp
+- Optional type filtering via `types` query parameter
+- Server timestamp included for use in subsequent sync calls
+- Integrates with DeletionLog for tracking deleted nodes
+
+**Response format:**
+
+```typescript
+interface SyncResponse {
+  updated: Node[]; // Nodes modified after timestamp
+  deleted: DeletionLogEntry[]; // Nodes deleted after timestamp
+  serverTime: string; // ISO 8601 timestamp for next sync
+  hasMore: boolean; // Reserved for future pagination
+}
+```
+
+**Example usage:**
+
+```typescript
+// Initial sync - get all changes since epoch
+const response = await fetch(
+  'http://localhost:4000/_sync?since=1970-01-01T00:00:00Z'
+);
+const { updated, deleted, serverTime } = await response.json();
+
+// Store serverTime for next sync
+localStorage.setItem('lastSync', serverTime);
+
+// Subsequent sync - get only recent changes
+const lastSync = localStorage.getItem('lastSync');
+const response = await fetch(`http://localhost:4000/_sync?since=${lastSync}`);
+```
+
+**Type filtering:**
+
+```
+GET /_sync?since=2024-01-01T00:00:00Z&types=Product,Collection
+```
+
+Only returns changes for the specified node types.
diff --git a/.changeset/websocket-server.md b/.changeset/websocket-server.md
new file mode 100644
index 0000000..c8b79a0
--- /dev/null
+++ b/.changeset/websocket-server.md
@@ -0,0 +1,53 @@
+---
+'universal-data-layer': minor
+---
+
+Add WebSocket server for real-time node change notifications
+
+This release introduces an opt-in WebSocket server that broadcasts node changes to connected clients in real-time. This enables local development machines to receive updates immediately when webhooks modify the data layer, eliminating the need for polling.
+
+**Features:**
+
+- `UDLWebSocketServer` class for real-time node change broadcasts
+- Broadcasts `node:created`, `node:updated`, `node:deleted` events with full node data
+- Client subscription filtering by node type (or `*` for all types)
+- Heartbeat mechanism for connection health monitoring
+- Configurable via `remote.websockets` in UDL config
+- Support for separate WebSocket port or attachment to HTTP server
+- Pass-through options for advanced `ws` configuration
+
+**Configuration:**
+
+```typescript
+export const { config } = defineConfig({
+  remote: {
+    websockets: {
+      enabled: true,
+      path: '/ws', // Default: '/ws'
+      port: 4001, // Optional: separate port
+      heartbeatIntervalMs: 30000, // Default: 30000
+    },
+  },
+});
+```
+
+**Client usage:**
+
+```typescript
+const ws = new WebSocket('ws://localhost:4000/ws');
+
+ws.onmessage = (event) => {
+  const message = JSON.parse(event.data);
+  if (message.type === 'node:created') {
+    console.log('New node:', message.data);
+  }
+};
+
+// Subscribe to specific types
+ws.send(JSON.stringify({ type: 'subscribe', data: ['Product', 'Collection'] }));
+```
+
+**Message types:**
+
+- Server → Client: `node:created`, `node:updated`, `node:deleted`, `connected`, `subscribed`, `pong`
+- Client → Server: `subscribe`, `ping`

From 69f6ff072bc82d98a7ef89f4a588b7db6cbedfa0 Mon Sep 17 00:00:00 2001
From: dawidurbanski <hi@dawidurbanski.com>
Date: Mon, 22 Dec 2025 20:46:01 +0100
Subject: [PATCH 22/46] feat(core): add remote sync for syncing from production
 UDL server

Add `remote.url` config option that allows local UDL servers to sync
data from a remote production server instead of sourcing from plugins.

Features:
- Fetches all nodes from remote /_sync endpoint on startup
- Connects to remote WebSocket for real-time updates (if enabled)
- Gracefully handles WebSocket unavailability
- Skips local plugin loading when remote.url is configured

New files:
- packages/core/src/websocket/client.ts - WebSocket client
- packages/core/src/sync/remote.ts - Remote sync logic

New exports:
- UDLWebSocketClient, WebSocketClientConfig
- fetchRemoteNodes, tryConnectRemoteWebSocket, initRemoteSync

Documentation:
- Added deployment section with production, standalone, webhook, and
  remote sync guides
---
 .changeset/remote-sync-feature.md             |  30 ++
 .../1.getting-started/1.installation.md       |   1 +
 docs/content/4.frameworks/1.nextjs.md         |   1 +
 docs/content/6.reference/1.configuration.md   |   1 +
 .../7.deployment/1.production-overview.md     | 102 ++++
 docs/content/7.deployment/2.standalone.md     |  77 +++
 docs/content/7.deployment/3.webhook-setup.md  | 470 ++++++++++++++++++
 docs/content/7.deployment/4.remote-sync.md    | 240 +++++++++
 packages/core/src/index.ts                    |   8 +
 packages/core/src/loader.ts                   |  14 +
 packages/core/src/start-server.ts             |  35 +-
 packages/core/src/sync/index.ts               |   7 +
 packages/core/src/sync/remote.ts              | 117 +++++
 packages/core/src/websocket/client.ts         | 261 ++++++++++
 packages/core/src/websocket/index.ts          |   2 +
 15 files changed, 1363 insertions(+), 3 deletions(-)
 create mode 100644 .changeset/remote-sync-feature.md
 create mode 100644 docs/content/7.deployment/1.production-overview.md
 create mode 100644 docs/content/7.deployment/2.standalone.md
 create mode 100644 docs/content/7.deployment/3.webhook-setup.md
 create mode 100644 docs/content/7.deployment/4.remote-sync.md
 create mode 100644 packages/core/src/sync/remote.ts
 create mode 100644 packages/core/src/websocket/client.ts

diff --git a/.changeset/remote-sync-feature.md b/.changeset/remote-sync-feature.md
new file mode 100644
index 0000000..546ea03
--- /dev/null
+++ b/.changeset/remote-sync-feature.md
@@ -0,0 +1,30 @@
+---
+'universal-data-layer': minor
+---
+
+feat(core): add remote sync for syncing data from production UDL server
+
+Added `remote.url` config option that allows local UDL servers to sync data from a remote production UDL server instead of sourcing from plugins directly.
+
+When configured:
+
+- Fetches all nodes from remote `/_sync` endpoint on startup
+- Automatically connects to remote WebSocket for real-time updates (if enabled on remote)
+- Skips local plugin loading
+
+New exports:
+
+- `UDLWebSocketClient` - WebSocket client for connecting to remote UDL
+- `fetchRemoteNodes` - Fetch all nodes from remote server
+- `tryConnectRemoteWebSocket` - Connect to remote WebSocket
+- `initRemoteSync` - Initialize remote sync (fetch + WebSocket)
+
+Usage:
+
+```typescript
+export const config = defineConfig({
+  remote: {
+    url: 'https://production-udl.example.com',
+  },
+});
+```
diff --git a/docs/content/1.getting-started/1.installation.md b/docs/content/1.getting-started/1.installation.md
index 45c092c..b0f417a 100644
--- a/docs/content/1.getting-started/1.installation.md
+++ b/docs/content/1.getting-started/1.installation.md
@@ -88,3 +88,4 @@ The `defineConfig` helper provides TypeScript autocompletion and validation. Sup
 
 - [Your First Query](/getting-started/first-query) - Make your first GraphQL query
 - [Exploring GraphQL](/getting-started/exploring-graphql) - Learn GraphQL basics with GraphiQL
+- [Production Deployment](/deployment/production-overview) - Deploy UDL for production use
diff --git a/docs/content/4.frameworks/1.nextjs.md b/docs/content/4.frameworks/1.nextjs.md
index af32b2d..98ca109 100644
--- a/docs/content/4.frameworks/1.nextjs.md
+++ b/docs/content/4.frameworks/1.nextjs.md
@@ -308,3 +308,4 @@ The example includes:
 
 - [Typed Queries](/codegen/typed-queries) - Learn more about TypedDocumentNode generation
 - [Querying Data](/using-plugins/querying-data) - Advanced query patterns
+- [Production Deployment](/deployment/production-overview) - Deploy UDL with your app
diff --git a/docs/content/6.reference/1.configuration.md b/docs/content/6.reference/1.configuration.md
index 0238a4b..0ad51f0 100644
--- a/docs/content/6.reference/1.configuration.md
+++ b/docs/content/6.reference/1.configuration.md
@@ -278,3 +278,4 @@ export const config = defineConfig({
 
 - [Plugin Overview](/using-plugins/overview) - How to use plugins
 - [Creating Plugins](/advanced/creating-plugins) - Build custom plugins
+- [Production Deployment](/deployment/production-overview) - Deploy UDL for production
diff --git a/docs/content/7.deployment/1.production-overview.md b/docs/content/7.deployment/1.production-overview.md
new file mode 100644
index 0000000..95a96b1
--- /dev/null
+++ b/docs/content/7.deployment/1.production-overview.md
@@ -0,0 +1,102 @@
+---
+title: Production Deployment
+description: Deploy UDL alongside your application
+navigation:
+  icon: i-lucide-server
+---
+
+## Overview
+
+While hosting UDL as a separate server is possible (see [Standalone Deployment](/deployment/standalone)), the most common setup is running it alongside your website. This keeps your deployment simple - one process, one deploy.
+
+## With Next.js Adapter
+
+The simplest approach for Next.js apps:
+
+```bash [Terminal]
+npm install @universal-data-layer/adapter-nextjs
+```
+
+```json [package.json]
+{
+  "scripts": {
+    "dev": "udl-next dev",
+    "build": "udl-next build",
+    "start": "udl-next start"
+  }
+}
+```
+
+Deploy to any platform. It just works.
+
+## Without the Adapter
+
+Run UDL and your app together:
+
+```json [package.json]
+{
+  "scripts": {
+    "dev": "universal-data-layer & next dev",
+    "build": "universal-data-layer --codegen && next build",
+    "start": "universal-data-layer & next start"
+  }
+}
+```
+
+Works with any framework - just run `universal-data-layer` alongside your server.
+
+## Configuration
+
+UDL automatically loads environment variables from `.env` files. Here's an example configuration using the Contentful source plugin:
+
+```typescript [udl.config.ts]
+import { defineConfig } from 'universal-data-layer';
+
+export const config = defineConfig({
+  plugins: [
+    {
+      name: '@universal-data-layer/plugin-source-contentful',
+      options: {
+        spaceId: process.env.CONTENTFUL_SPACE_ID,
+        accessToken: process.env.CONTENTFUL_ACCESS_TOKEN,
+      },
+    },
+  ],
+});
+```
+
+## Endpoints
+
+Once running, UDL exposes these endpoints:
+
+| Endpoint | Method | Description |
+| -------- | ------ | ----------- |
+| `/graphql` | POST | GraphQL API |
+| `/graphiql` | GET | Interactive GraphQL IDE |
+| `/health` | GET | Health check (returns 200 if running) |
+| `/ready` | GET | Readiness check (returns 200 when ready) |
+| `/_webhooks/:plugin/:path` | POST | Webhook receiver |
+| `/_sync` | GET | Sync API for partial updates |
+
+### Health Check Response
+
+```json
+{
+  "status": "ok",
+  "timestamp": "2025-01-15T10:30:00.000Z"
+}
+```
+
+### Sync API
+
+Get changes since a timestamp:
+
+```bash
+curl "http://localhost:4000/_sync?since=2025-01-15T10:00:00Z"
+```
+
+## Next Steps
+
+- [Standalone Deployment](/deployment/standalone) - Run UDL as a separate server
+- [Remote Sync](/deployment/remote-sync) - Sync data from a production UDL server
+- [Webhook Setup](/deployment/webhook-setup) - Configure CMS webhooks
diff --git a/docs/content/7.deployment/2.standalone.md b/docs/content/7.deployment/2.standalone.md
new file mode 100644
index 0000000..9d10f0e
--- /dev/null
+++ b/docs/content/7.deployment/2.standalone.md
@@ -0,0 +1,77 @@
+---
+title: Standalone Deployment
+description: Run UDL as a separate server
+navigation:
+  icon: i-lucide-server-cog
+---
+
+## Prerequisites
+
+- Node.js 20 or higher
+
+## Simplest Scenario
+
+Create a `udl.config.ts` file:
+
+```typescript [udl.config.ts]
+import { defineConfig } from 'universal-data-layer';
+
+export const config = defineConfig({
+  port: 4000,
+});
+```
+
+Run UDL:
+
+```bash
+npx universal-data-layer
+```
+
+If your server exposes port 4000, UDL is now accessible at `http://your-server:4000/graphql`.
+
+To bind to a different port, update your config or use your web server's port forwarding.
+
+## With Plugins
+
+Initialize a project:
+
+```bash
+npm init -y
+```
+
+Install your plugins:
+
+```bash
+npm install universal-data-layer @universal-data-layer/plugin-source-contentful
+```
+
+Create `udl.config.ts` with plugin options:
+
+```typescript [udl.config.ts]
+import { defineConfig } from 'universal-data-layer';
+
+export const config = defineConfig({
+  port: 4000,
+  plugins: [
+    {
+      name: '@universal-data-layer/plugin-source-contentful',
+      options: {
+        spaceId: process.env.CONTENTFUL_SPACE_ID,
+        accessToken: process.env.CONTENTFUL_ACCESS_TOKEN,
+      },
+    },
+  ],
+});
+```
+
+Run UDL:
+
+```bash
+npx universal-data-layer
+```
+
+## Next Steps
+
+- [Remote Sync](/deployment/remote-sync) - Sync data from a production UDL server
+- [Production Deployment](/deployment/production-overview) - Run alongside your app
+- [Webhook Setup](/deployment/webhook-setup) - Configure CMS webhooks
diff --git a/docs/content/7.deployment/3.webhook-setup.md b/docs/content/7.deployment/3.webhook-setup.md
new file mode 100644
index 0000000..1062b14
--- /dev/null
+++ b/docs/content/7.deployment/3.webhook-setup.md
@@ -0,0 +1,470 @@
+---
+title: Webhook Setup
+description: Configure webhooks from external data sources to UDL
+navigation:
+  icon: i-lucide-webhook
+---
+
+## Overview
+
+Webhooks allow your content management systems and data sources to notify UDL when content changes. This enables near real-time updates without constant polling.
+
+## Webhook Architecture
+
+```
+┌─────────────────┐     Content Change     ┌─────────────────┐
+│   Contentful    │ ────────────────────▶  │   UDL Server    │
+│   Shopify       │     POST webhook       │                 │
+│   Your CMS      │                        │   /_webhooks/   │
+└─────────────────┘                        └────────┬────────┘
+                                                    │
+                                           Queue + Debounce
+                                                    │
+                                                    ▼
+                                           ┌─────────────────┐
+                                           │  Batch Process  │
+                                           │  Update Nodes   │
+                                           └─────────────────┘
+```
+
+UDL webhooks are:
+- **Queued**: Rapid consecutive webhooks are batched together
+- **Debounced**: Processing waits briefly for more webhooks to arrive
+- **Idempotent**: Safe to receive duplicate webhooks
+
+## Webhook URL Format
+
+All webhooks follow this URL pattern:
+
+```
+POST https://your-udl-server.com/_webhooks/{pluginName}/{path}
+```
+
+| Component | Description | Example |
+| --------- | ----------- | ------- |
+| `pluginName` | Plugin identifier | `contentful`, `shopify` |
+| `path` | Webhook path | `sync`, `entry-update` |
+
+### Examples
+
+```bash
+# Contentful default webhook
+POST https://udl.your-domain.com/_webhooks/contentful/sync
+
+# Custom plugin webhook
+POST https://udl.your-domain.com/_webhooks/my-plugin/content-update
+```
+
+## Default Webhook Handler
+
+UDL provides a standardized webhook handler for CRUD operations. Plugins can opt into this handler for common use cases.
+
+### Payload Format
+
+```typescript
+interface DefaultWebhookPayload {
+  operation: 'create' | 'update' | 'delete' | 'upsert';
+  nodeId: string;
+  nodeType: string;
+  data?: Record<string, unknown>;  // Required for create/update/upsert
+}
+```
+
+### Operations
+
+| Operation | Behavior | Returns |
+| --------- | -------- | ------- |
+| `create` | Create new node | 201 Created, 409 if exists |
+| `update` | Update existing node | 200 OK, 404 if not found |
+| `delete` | Remove node | 200 OK, 404 if not found |
+| `upsert` | Create or update | 200 OK (always succeeds) |
+
+### Example Payloads
+
+**Create a new product:**
+```json
+{
+  "operation": "create",
+  "nodeId": "product-123",
+  "nodeType": "Product",
+  "data": {
+    "title": "New Product",
+    "price": 99.99,
+    "slug": "new-product"
+  }
+}
+```
+
+**Update existing product:**
+```json
+{
+  "operation": "update",
+  "nodeId": "product-123",
+  "nodeType": "Product",
+  "data": {
+    "title": "Updated Product",
+    "price": 79.99
+  }
+}
+```
+
+**Delete a product:**
+```json
+{
+  "operation": "delete",
+  "nodeId": "product-123",
+  "nodeType": "Product"
+}
+```
+
+**Upsert (create or update):**
+```json
+{
+  "operation": "upsert",
+  "nodeId": "product-456",
+  "nodeType": "Product",
+  "data": {
+    "title": "Product",
+    "price": 49.99
+  }
+}
+```
+
+## Contentful Webhook Setup
+
+### Step 1: Get Your Webhook URL
+
+Your Contentful webhook URL follows this pattern:
+
+```
+https://your-udl-server.com/_webhooks/contentful/sync
+```
+
+### Step 2: Configure in Contentful
+
+1. Go to **Settings** → **Webhooks** in Contentful
+2. Click **Add Webhook**
+3. Configure:
+
+| Field | Value |
+| ----- | ----- |
+| Name | `UDL Sync` |
+| URL | `https://your-udl-server.com/_webhooks/contentful/sync` |
+| Method | POST |
+
+### Step 3: Select Events
+
+Under **Triggers**, select the events you want to sync:
+
+**Entry Events:**
+- [x] Publish
+- [x] Unpublish
+- [x] Delete
+
+**Asset Events:**
+- [x] Publish
+- [x] Unpublish
+- [x] Delete
+
+### Step 4: Configure Headers
+
+Add any required headers:
+
+| Header | Value |
+| ------ | ----- |
+| `Content-Type` | `application/json` |
+| `X-Webhook-Secret` | Your secret (if using signature verification) |
+
+### Step 5: Test the Webhook
+
+1. Click **Save**
+2. Use the **Test** button to send a test payload
+3. Check UDL logs for received webhook:
+
+```bash
+# Docker
+docker logs udl
+
+# systemd
+sudo journalctl -u udl -f
+
+# Railway CLI
+railway logs -f
+```
+
+## Shopify Webhook Setup
+
+### Step 1: Determine Webhook URL
+
+```
+https://your-udl-server.com/_webhooks/shopify/sync
+```
+
+### Step 2: Configure via Admin
+
+1. Go to **Settings** → **Notifications** in Shopify Admin
+2. Scroll to **Webhooks**
+3. Click **Create webhook**
+
+### Step 3: Select Events
+
+Configure webhooks for these topics:
+
+| Topic | Description |
+| ----- | ----------- |
+| `products/create` | New product created |
+| `products/update` | Product updated |
+| `products/delete` | Product deleted |
+| `collections/create` | Collection created |
+| `collections/update` | Collection updated |
+| `collections/delete` | Collection deleted |
+
+### Step 4: Configure Each Webhook
+
+For each event:
+
+| Field | Value |
+| ----- | ----- |
+| Format | JSON |
+| URL | `https://your-udl-server.com/_webhooks/shopify/sync` |
+| API version | Latest stable |
+
+## Custom Webhook Integration
+
+For other data sources, implement a custom webhook handler:
+
+### 1. Register Webhook in Plugin
+
+```typescript [udl.config.ts]
+import { defineConfig, WebhookRegistry } from 'universal-data-layer';
+
+export const config = defineConfig({
+  type: 'source',
+  name: 'my-plugin',
+});
+
+export function onLoad({ webhookRegistry }: { webhookRegistry: WebhookRegistry }) {
+  webhookRegistry.register({
+    pluginName: 'my-plugin',
+    path: 'content-update',
+    handler: async (req, res, context) => {
+      const { body, actions } = context;
+
+      // Process the webhook payload
+      await actions.createNode({
+        internal: {
+          id: body.id,
+          type: 'MyContent',
+          owner: 'my-plugin',
+        },
+        ...body.data,
+      });
+
+      res.writeHead(200);
+      res.end(JSON.stringify({ success: true }));
+    },
+  });
+}
+```
+
+### 2. Configure Source to Send Webhooks
+
+Point your data source to:
+
+```
+POST https://your-udl-server.com/_webhooks/my-plugin/content-update
+```
+
+## Webhook Security
+
+### Signature Verification
+
+Verify webhook signatures to ensure requests come from legitimate sources:
+
+```typescript [Custom handler with signature verification]
+webhookRegistry.register({
+  pluginName: 'my-plugin',
+  path: 'secure-webhook',
+  verifySignature: async (req, rawBody) => {
+    const signature = req.headers['x-webhook-signature'];
+    const secret = process.env['WEBHOOK_SECRET'];
+
+    if (!signature || !secret) {
+      return false;
+    }
+
+    const crypto = await import('node:crypto');
+    const expectedSignature = crypto
+      .createHmac('sha256', secret)
+      .update(rawBody)
+      .digest('hex');
+
+    return signature === expectedSignature;
+  },
+  handler: async (req, res, context) => {
+    // Handle verified webhook
+  },
+});
+```
+
+### IP Allowlisting
+
+In production, consider restricting webhook endpoints to known IPs using your reverse proxy:
+
+```nginx [nginx.conf]
+location /_webhooks/ {
+    # Contentful IPs (example - check current IPs)
+    allow 52.213.82.0/24;
+    allow 52.213.83.0/24;
+    deny all;
+
+    proxy_pass http://udl_backend;
+}
+```
+
+### HTTPS Only
+
+Always use HTTPS for webhook endpoints:
+- Encrypts payload in transit
+- Prevents man-in-the-middle attacks
+- Required by most CMS platforms
+
+## Testing Webhooks
+
+### Using curl
+
+Test your webhook endpoint manually:
+
+```bash [Terminal]
+# Test upsert operation
+curl -X POST https://your-udl-server.com/_webhooks/contentful/sync \
+  -H "Content-Type: application/json" \
+  -d '{
+    "operation": "upsert",
+    "nodeId": "test-123",
+    "nodeType": "TestContent",
+    "data": {
+      "title": "Test Content",
+      "body": "This is a test"
+    }
+  }'
+```
+
+Expected response:
+
+```json
+{
+  "queued": true
+}
+```
+
+### Verify Node Was Created
+
+```bash [Terminal]
+# Query for the created node
+curl -X POST https://your-udl-server.com/graphql \
+  -H "Content-Type: application/json" \
+  -d '{
+    "query": "{ testContent(id: \"test-123\") { title body } }"
+  }'
+```
+
+### Local Development Testing
+
+For local testing without exposing your server:
+
+**Option 1: ngrok**
+```bash [Terminal]
+# Expose local UDL to internet
+ngrok http 4000
+
+# Use the ngrok URL in your CMS webhook config
+# https://abc123.ngrok.io/_webhooks/contentful/sync
+```
+
+**Option 2: Webhook.site**
+1. Go to [webhook.site](https://webhook.site)
+2. Configure CMS to send to webhook.site URL
+3. Inspect payloads to understand format
+4. Replay to local server with curl
+
+## Debugging
+
+### Check UDL Logs
+
+Webhook activity is logged:
+
+```bash
+# Successful webhook
+Webhook received: contentful/sync
+✅ Default webhook [contentful]: Created node Product:product-123
+
+# Failed webhook
+⚠️ Default webhook handler [contentful]: Invalid payload received
+```
+
+### Common Issues
+
+**404 Not Found**
+
+- Verify URL format: `/_webhooks/{plugin}/{path}`
+- Check plugin is registered
+- Verify webhook path matches registration
+
+**400 Invalid Payload**
+
+- Check JSON is valid
+- Verify required fields: `operation`, `nodeId`, `nodeType`
+- Include `data` for create/update/upsert operations
+
+**401 Invalid Signature**
+
+- Verify secret matches on both sides
+- Check signature header name
+- Ensure raw body is used for signature calculation
+
+**413 Payload Too Large**
+
+- UDL limits webhook bodies to 1MB
+- For larger payloads, fetch data separately using nodeId
+
+### Webhook Queue Status
+
+Webhooks are queued before processing. If updates seem delayed:
+
+1. Check batch processing is running
+2. Verify no errors in processing logs
+3. Default debounce is 100ms - rapid webhooks are batched
+
+## Outbound Webhooks
+
+UDL can notify external services when nodes change:
+
+```typescript [udl.config.ts]
+import { defineConfig, OutboundWebhookManager } from 'universal-data-layer';
+
+const webhookManager = new OutboundWebhookManager({
+  url: process.env['EXTERNAL_WEBHOOK_URL'],
+  headers: {
+    'Authorization': `Bearer ${process.env['WEBHOOK_TOKEN']}`,
+  },
+});
+
+// Trigger when nodes are created/updated
+webhookManager.notify({
+  event: 'node.updated',
+  nodeType: 'Product',
+  nodeId: 'product-123',
+});
+```
+
+Use cases:
+- Trigger Vercel revalidation
+- Notify search index to re-crawl
+- Update external caches
+- Trigger downstream builds
+
+## Next Steps
+
+- [Production Deployment](/deployment/production-overview) - Run alongside your app
+- [Standalone Deployment](/deployment/standalone) - Run UDL as a separate server
diff --git a/docs/content/7.deployment/4.remote-sync.md b/docs/content/7.deployment/4.remote-sync.md
new file mode 100644
index 0000000..c1567f9
--- /dev/null
+++ b/docs/content/7.deployment/4.remote-sync.md
@@ -0,0 +1,240 @@
+---
+title: Remote Sync
+description: Sync data from a remote UDL server for local development
+navigation:
+  icon: i-lucide-cloud-download
+---
+
+## Overview
+
+Remote sync allows a local UDL server to fetch and mirror data from a production UDL server. This is useful for local development when you want to work with real production data without configuring CMS credentials locally.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                         PRODUCTION SERVER                               │
+│  ┌─────────────┐     ┌─────────────┐     ┌─────────────────────────┐   │
+│  │ Contentful  │────▶│             │────▶│                         │   │
+│  │ Shopify     │     │   Plugins   │     │       Node Store        │   │
+│  │ Custom CMS  │     │             │     │                         │   │
+│  └─────────────┘     └─────────────┘     └───────────┬─────────────┘   │
+│                                                      │                  │
+│                                          ┌───────────┴───────────┐      │
+│                                          │                       │      │
+│                                     /_sync              /ws (optional)  │
+│                                          │                       │      │
+└──────────────────────────────────────────┼───────────────────────┼──────┘
+                                           │                       │
+                                           │    Initial Fetch      │  Real-time
+                                           │    (all nodes)        │  Updates
+                                           │                       │
+                                           ▼                       ▼
+┌──────────────────────────────────────────────────────────────────────────┐
+│                          LOCAL DEV SERVER                                │
+│                                                                          │
+│  ┌─────────────────────────────────────────────────────────────────┐    │
+│  │                         Node Store                               │    │
+│  │                    (mirror of production)                        │    │
+│  └─────────────────────────────────────────────────────────────────┘    │
+│                                    │                                     │
+│                                    ▼                                     │
+│                              /graphql                                    │
+│                                    │                                     │
+│                                    ▼                                     │
+│                           Your Application                               │
+│                                                                          │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+## How It Works
+
+### Step 1: Initial Sync
+
+When the local server starts with `remote.url` configured:
+
+```
+Local Server                              Remote Server
+     │                                          │
+     │  GET /_sync?since=1970-01-01T00:00:00Z   │
+     │─────────────────────────────────────────▶│
+     │                                          │
+     │         { updated: [...], deleted: [] }  │
+     │◀─────────────────────────────────────────│
+     │                                          │
+     │  Populate local node store               │
+     │                                          │
+```
+
+The local server requests all nodes by using the epoch timestamp. The remote server returns every node in its store.
+
+### Step 2: WebSocket Connection (Optional)
+
+If the remote server has WebSockets enabled, the local server connects for real-time updates:
+
+```
+Local Server                              Remote Server
+     │                                          │
+     │  WebSocket: ws://remote/ws               │
+     │─────────────────────────────────────────▶│
+     │                                          │
+     │  { type: "subscribe", data: "*" }        │
+     │─────────────────────────────────────────▶│
+     │                                          │
+     │  { type: "subscribed", types: [...] }    │
+     │◀─────────────────────────────────────────│
+     │                                          │
+```
+
+### Step 3: Real-time Updates
+
+When content changes on the remote server, updates flow automatically:
+
+```
+CMS Webhook                Remote Server                Local Server
+     │                           │                            │
+     │  Content Updated          │                            │
+     │──────────────────────────▶│                            │
+     │                           │                            │
+     │                           │  { type: "node:updated",   │
+     │                           │    nodeId: "...",          │
+     │                           │    data: {...} }           │
+     │                           │───────────────────────────▶│
+     │                           │                            │
+     │                           │          Update local store│
+     │                           │                            │
+```
+
+## Configuration
+
+### Basic Setup
+
+```typescript [udl.config.ts]
+import { defineConfig } from 'universal-data-layer';
+
+export const config = defineConfig({
+  port: 4000,
+  remote: {
+    url: 'https://production-udl.example.com',
+  },
+});
+```
+
+### What Gets Skipped
+
+When `remote.url` is set, the local server:
+
+- **Skips** plugin loading (no `sourceNodes` calls)
+- **Skips** webhook handlers (remote handles those)
+- **Keeps** local GraphQL endpoint active
+- **Keeps** local codegen working (if configured)
+
+## Use Cases
+
+### Local Development with Production Data
+
+Work with real content without CMS credentials:
+
+```typescript [udl.config.ts]
+export const config = defineConfig({
+  remote: {
+    url: process.env.PRODUCTION_UDL_URL,
+  },
+  codegen: {
+    output: './generated',
+  },
+});
+```
+
+### CI/CD Preview Builds
+
+Preview deployments can sync from production:
+
+```typescript [udl.config.ts]
+export const config = defineConfig({
+  remote: {
+    // Production UDL for preview builds
+    url: process.env.CI ? process.env.PRODUCTION_UDL_URL : undefined,
+  },
+  plugins: process.env.CI ? [] : [
+    // Local dev uses plugins directly
+    { name: '@universal-data-layer/plugin-source-contentful', options: {...} },
+  ],
+});
+```
+
+### Staging Environments
+
+Staging can mirror production data:
+
+```
+Production UDL ──────▶ Staging UDL (remote sync)
+       │
+       └─────────────▶ Local Dev (remote sync)
+```
+
+## WebSocket Behavior
+
+The WebSocket connection is optional and graceful:
+
+| Remote Server State | Local Server Behavior |
+|--------------------|-----------------------|
+| WebSocket enabled | Connects and receives real-time updates |
+| WebSocket disabled | Works fine, just no real-time updates |
+| WebSocket unavailable | Logs message, continues without it |
+
+To enable WebSocket on the production server:
+
+```typescript [udl.config.ts (production)]
+export const config = defineConfig({
+  plugins: [...],
+  remote: {
+    websockets: {
+      enabled: true,
+    },
+  },
+});
+```
+
+## Comparison: Remote Sync vs Local Plugins
+
+| Aspect | Remote Sync | Local Plugins |
+|--------|-------------|---------------|
+| CMS credentials | Not needed locally | Required locally |
+| Data freshness | Mirrors production | Direct from CMS |
+| Webhook handling | Remote server | Local server |
+| Network dependency | Requires remote UDL | Requires CMS APIs |
+| Setup complexity | Minimal | Requires plugin config |
+
+## Troubleshooting
+
+### Connection Refused
+
+```
+Error: Failed to fetch from remote UDL: ECONNREFUSED
+```
+
+- Verify the remote URL is correct
+- Check if the remote server is running
+- Ensure network/firewall allows the connection
+
+### Empty Node Store
+
+If no nodes are loaded:
+
+1. Check remote server has data: `curl https://remote/_sync?since=1970-01-01T00:00:00Z`
+2. Verify the response contains `updated` array with nodes
+3. Check for errors in local server logs
+
+### WebSocket Not Connecting
+
+This is normal if the remote server doesn't have WebSocket enabled. The local server will log:
+
+```
+📡 Remote WebSocket not available (this is fine if remote has websockets disabled)
+```
+
+## Next Steps
+
+- [Production Deployment](/deployment/production-overview) - Deploy the production server
+- [Webhook Setup](/deployment/webhook-setup) - Configure CMS webhooks on production
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 517026c..94fa8be 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -98,6 +98,11 @@ export {
   type DeletionNodeInfo,
   defaultDeletionLog,
   setDefaultDeletionLog,
+  // Remote sync utilities
+  fetchRemoteNodes,
+  tryConnectRemoteWebSocket,
+  initRemoteSync,
+  type RemoteSyncConfig,
 } from './sync/index.js';
 
 // Re-export sync handler types
@@ -171,6 +176,9 @@ export {
   type SubscribeMessage,
   type PingMessage,
   type ClientSubscription,
+  // WebSocket client for connecting to remote UDL
+  UDLWebSocketClient,
+  type WebSocketClientConfig,
 } from './websocket/index.js';
 
 // Re-export WebSocket config type from loader
diff --git a/packages/core/src/loader.ts b/packages/core/src/loader.ts
index ca25a23..f2ee888 100644
--- a/packages/core/src/loader.ts
+++ b/packages/core/src/loader.ts
@@ -204,6 +204,20 @@ export interface WebSocketConfig {
  * Configuration for remote data synchronization.
  */
 export interface RemoteConfig {
+  /**
+   * URL of a remote UDL server to sync data from.
+   * When set, the local server fetches data from the remote server
+   * instead of sourcing from plugins directly.
+   *
+   * @example
+   * ```typescript
+   * remote: {
+   *   url: 'https://production-udl.example.com',
+   * }
+   * ```
+   */
+  url?: string;
+
   /**
    * Webhook queue and processing configuration.
    */
diff --git a/packages/core/src/start-server.ts b/packages/core/src/start-server.ts
index 81fc233..52dc0a6 100644
--- a/packages/core/src/start-server.ts
+++ b/packages/core/src/start-server.ts
@@ -25,6 +25,8 @@ import {
   setDefaultWebSocketServer,
   getDefaultWebSocketServer,
 } from '@/websocket/index.js';
+import { initRemoteSync } from '@/sync/remote.js';
+import type { UDLWebSocketClient } from '@/websocket/client.js';
 
 export interface StartServerOptions {
   port?: number;
@@ -106,8 +108,28 @@ export async function startServer(options: StartServerOptions = {}) {
   // Determine if caching is enabled (per-plugin caching is handled in loadPlugins)
   const cacheEnabled = userConfig.cache !== false;
 
-  // Load main app config plugins
-  if (userConfig.plugins && userConfig.plugins.length > 0) {
+  // Track remote WebSocket client for cleanup
+  let remoteWsClient: UDLWebSocketClient | null = null;
+
+  // Check if we should sync from a remote UDL server
+  if (userConfig.remote?.url) {
+    // Remote mode: fetch data from remote UDL instead of loading plugins
+    console.log(`📡 Remote mode: syncing from ${userConfig.remote.url}`);
+
+    remoteWsClient = await initRemoteSync(
+      {
+        url: userConfig.remote.url,
+        // Note: WebSocket client uses sensible defaults (5s reconnect, 30s ping)
+        // Custom client config can be added to RemoteSyncConfig if needed
+      },
+      defaultStore
+    );
+
+    if (remoteWsClient) {
+      console.log('📡 Connected to remote WebSocket for real-time updates');
+    }
+  } else if (userConfig.plugins && userConfig.plugins.length > 0) {
+    // Normal mode: load plugins and source nodes locally
     console.log('Loading plugins...');
     // Track plugin names before loading
     // Note: The actual owner name is determined by the plugin's config.name or basename
@@ -138,7 +160,7 @@ export async function startServer(options: StartServerOptions = {}) {
     }
   }
 
-  // Mark node store as ready after plugins have loaded
+  // Mark node store as ready after plugins have loaded or remote sync completed
   setReady('nodeStore', true);
 
   // Track main app codegen config if present (after collecting plugin names)
@@ -406,6 +428,13 @@ export async function startServer(options: StartServerOptions = {}) {
         console.log('🔌 WebSocket server closed');
       }
 
+      // Close remote WebSocket client if connected
+      if (remoteWsClient) {
+        console.log('📡 Closing remote WebSocket client...');
+        remoteWsClient.close();
+        console.log('📡 Remote WebSocket client closed');
+      }
+
       // Stop accepting new connections and wait for in-flight requests
       server.close(() => {
         console.log('✅ HTTP server closed');
diff --git a/packages/core/src/sync/index.ts b/packages/core/src/sync/index.ts
index 6019738..43a89c6 100644
--- a/packages/core/src/sync/index.ts
+++ b/packages/core/src/sync/index.ts
@@ -9,3 +9,10 @@ export {
   defaultDeletionLog,
   setDefaultDeletionLog,
 } from './defaultDeletionLog.js';
+
+export {
+  fetchRemoteNodes,
+  tryConnectRemoteWebSocket,
+  initRemoteSync,
+  type RemoteSyncConfig,
+} from './remote.js';
diff --git a/packages/core/src/sync/remote.ts b/packages/core/src/sync/remote.ts
new file mode 100644
index 0000000..fe00c09
--- /dev/null
+++ b/packages/core/src/sync/remote.ts
@@ -0,0 +1,117 @@
+import type { NodeStore } from '@/nodes/store.js';
+import {
+  UDLWebSocketClient,
+  type WebSocketClientConfig,
+} from '@/websocket/client.js';
+import type { SyncResponse } from '@/handlers/sync.js';
+
+/**
+ * Configuration for remote sync.
+ */
+export interface RemoteSyncConfig {
+  /** Base URL of the remote UDL server (e.g., https://production-udl.example.com) */
+  url: string;
+  /** WebSocket configuration overrides */
+  websocket?: Partial<Omit<WebSocketClientConfig, 'url'>>;
+}
+
+/**
+ * Fetch all nodes from a remote UDL server.
+ *
+ * Uses the /_sync endpoint with epoch time to get all nodes.
+ *
+ * @param url - Base URL of the remote UDL server
+ * @param store - Local node store to populate
+ */
+export async function fetchRemoteNodes(
+  url: string,
+  store: NodeStore
+): Promise<void> {
+  const syncUrl = new URL('/_sync', url);
+  // Use epoch to get all nodes
+  syncUrl.searchParams.set('since', '1970-01-01T00:00:00Z');
+
+  console.log(`📡 Fetching nodes from remote UDL: ${url}`);
+
+  const response = await fetch(syncUrl.toString());
+
+  if (!response.ok) {
+    throw new Error(
+      `Failed to fetch from remote UDL: ${response.status} ${response.statusText}`
+    );
+  }
+
+  const data = (await response.json()) as SyncResponse;
+
+  // Populate the local store
+  let count = 0;
+  for (const node of data.updated) {
+    store.set(node);
+    count++;
+  }
+
+  console.log(`📡 Loaded ${count} nodes from remote UDL`);
+}
+
+/**
+ * Try to connect to the remote UDL WebSocket server.
+ *
+ * This will only succeed if the remote server has WebSocket enabled.
+ * Fails gracefully if WebSocket is not available.
+ *
+ * @param url - Base URL of the remote UDL server
+ * @param store - Local node store to update with changes
+ * @param config - Optional WebSocket configuration overrides
+ * @returns The WebSocket client if connected, null if connection failed
+ */
+export async function tryConnectRemoteWebSocket(
+  url: string,
+  store: NodeStore,
+  config?: Partial<Omit<WebSocketClientConfig, 'url'>>
+): Promise<UDLWebSocketClient | null> {
+  // Convert HTTP URL to WebSocket URL
+  const wsUrl = url.replace(/^http/, 'ws') + '/ws';
+
+  const client = new UDLWebSocketClient({
+    url: wsUrl,
+    ...config,
+  });
+
+  try {
+    await client.connect(store);
+    return client;
+  } catch {
+    // WebSocket not available on remote server
+    console.log(
+      `📡 Remote WebSocket not available (this is fine if remote has websockets disabled)`
+    );
+    return null;
+  }
+}
+
+/**
+ * Initialize sync from a remote UDL server.
+ *
+ * 1. Fetches all nodes from the remote server
+ * 2. Attempts to connect to WebSocket for real-time updates
+ *
+ * @param config - Remote sync configuration
+ * @param store - Local node store
+ * @returns WebSocket client if connected, null otherwise
+ */
+export async function initRemoteSync(
+  config: RemoteSyncConfig,
+  store: NodeStore
+): Promise<UDLWebSocketClient | null> {
+  // Fetch initial data
+  await fetchRemoteNodes(config.url, store);
+
+  // Try to connect WebSocket for real-time updates
+  const wsClient = await tryConnectRemoteWebSocket(
+    config.url,
+    store,
+    config.websocket
+  );
+
+  return wsClient;
+}
diff --git a/packages/core/src/websocket/client.ts b/packages/core/src/websocket/client.ts
new file mode 100644
index 0000000..e9b64d4
--- /dev/null
+++ b/packages/core/src/websocket/client.ts
@@ -0,0 +1,261 @@
+import WebSocket from 'ws';
+import type { NodeStore } from '@/nodes/store.js';
+import type {
+  ServerMessage,
+  NodeChangeMessage,
+  ClientMessage,
+} from './server.js';
+
+/**
+ * Configuration for the WebSocket client.
+ */
+export interface WebSocketClientConfig {
+  /** WebSocket URL to connect to (e.g., ws://localhost:4000/ws) */
+  url: string;
+  /** Reconnect delay in milliseconds after connection loss. Default: 5000 */
+  reconnectDelayMs?: number;
+  /** Maximum reconnect attempts. Default: Infinity */
+  maxReconnectAttempts?: number;
+  /** Ping interval in milliseconds. Default: 30000 */
+  pingIntervalMs?: number;
+}
+
+/**
+ * WebSocket client for connecting to a remote UDL server.
+ *
+ * Receives real-time node change notifications and updates the local store.
+ *
+ * @example
+ * ```typescript
+ * const client = new UDLWebSocketClient({
+ *   url: 'ws://production-udl.example.com/ws',
+ * });
+ *
+ * await client.connect(localStore);
+ * ```
+ */
+export class UDLWebSocketClient {
+  private config: Required<WebSocketClientConfig>;
+  private ws: WebSocket | null = null;
+  private store: NodeStore | null = null;
+  private reconnectAttempts = 0;
+  private reconnectTimeout: ReturnType<typeof setTimeout> | null = null;
+  private pingInterval: ReturnType<typeof setInterval> | null = null;
+  private isClosing = false;
+
+  constructor(config: WebSocketClientConfig) {
+    this.config = {
+      url: config.url,
+      reconnectDelayMs: config.reconnectDelayMs ?? 5000,
+      maxReconnectAttempts: config.maxReconnectAttempts ?? Infinity,
+      pingIntervalMs: config.pingIntervalMs ?? 30000,
+    };
+  }
+
+  /**
+   * Connect to the remote WebSocket server and start syncing.
+   *
+   * @param store - Local node store to update with remote changes
+   * @returns Promise that resolves when connected, rejects on failure
+   */
+  connect(store: NodeStore): Promise<void> {
+    this.store = store;
+    this.isClosing = false;
+
+    return new Promise((resolve, reject) => {
+      this.createConnection(resolve, reject);
+    });
+  }
+
+  /**
+   * Create a WebSocket connection.
+   */
+  private createConnection(
+    onConnect?: () => void,
+    onError?: (error: Error) => void
+  ): void {
+    try {
+      this.ws = new WebSocket(this.config.url);
+
+      this.ws.on('open', () => {
+        console.log(`🔌 Connected to remote UDL: ${this.config.url}`);
+        this.reconnectAttempts = 0;
+
+        // Subscribe to all node types
+        this.send({ type: 'subscribe', data: '*' });
+
+        // Start ping interval
+        this.startPingInterval();
+
+        onConnect?.();
+      });
+
+      this.ws.on('message', (data: Buffer) => {
+        this.handleMessage(data);
+      });
+
+      this.ws.on('close', () => {
+        this.stopPingInterval();
+        if (!this.isClosing) {
+          console.log('🔌 Connection closed, attempting reconnect...');
+          this.scheduleReconnect();
+        }
+      });
+
+      this.ws.on('error', (error) => {
+        console.error('🔌 WebSocket error:', error.message);
+        if (this.reconnectAttempts === 0 && onError) {
+          // First connection attempt failed
+          onError(error);
+        }
+      });
+    } catch (error) {
+      onError?.(error as Error);
+    }
+  }
+
+  /**
+   * Handle incoming message from server.
+   */
+  private handleMessage(data: Buffer): void {
+    try {
+      const message = JSON.parse(data.toString()) as ServerMessage;
+
+      switch (message.type) {
+        case 'connected':
+          console.log('🔌 Remote UDL:', message.data.message);
+          break;
+
+        case 'subscribed':
+          console.log('🔌 Subscribed to node types:', message.data.types);
+          break;
+
+        case 'pong':
+          // Connection is alive
+          break;
+
+        case 'node:created':
+        case 'node:updated':
+          this.handleNodeUpdate(message);
+          break;
+
+        case 'node:deleted':
+          this.handleNodeDelete(message);
+          break;
+      }
+    } catch {
+      // Invalid JSON, ignore
+    }
+  }
+
+  /**
+   * Handle node creation or update from remote.
+   */
+  private handleNodeUpdate(message: NodeChangeMessage): void {
+    if (!this.store || !message.data) return;
+
+    const node = message.data as Record<string, unknown>;
+
+    // Ensure node has required internal structure
+    if (!node['internal']) {
+      node['internal'] = {
+        id: message.nodeId,
+        type: message.nodeType,
+      };
+    }
+
+    // Cast to Node type for store.set
+    this.store.set(node as unknown as import('@/nodes/types.js').Node);
+    console.log(
+      `🔄 Remote ${message.type}: ${message.nodeType}:${message.nodeId}`
+    );
+  }
+
+  /**
+   * Handle node deletion from remote.
+   */
+  private handleNodeDelete(message: NodeChangeMessage): void {
+    if (!this.store) return;
+
+    this.store.delete(message.nodeId);
+    console.log(
+      `🔄 Remote node:deleted: ${message.nodeType}:${message.nodeId}`
+    );
+  }
+
+  /**
+   * Send a message to the server.
+   */
+  private send(message: ClientMessage): void {
+    if (this.ws?.readyState === WebSocket.OPEN) {
+      this.ws.send(JSON.stringify(message));
+    }
+  }
+
+  /**
+   * Start the ping interval to keep connection alive.
+   */
+  private startPingInterval(): void {
+    this.stopPingInterval();
+    this.pingInterval = setInterval(() => {
+      this.send({ type: 'ping' });
+    }, this.config.pingIntervalMs);
+  }
+
+  /**
+   * Stop the ping interval.
+   */
+  private stopPingInterval(): void {
+    if (this.pingInterval) {
+      clearInterval(this.pingInterval);
+      this.pingInterval = null;
+    }
+  }
+
+  /**
+   * Schedule a reconnection attempt.
+   */
+  private scheduleReconnect(): void {
+    if (this.isClosing) return;
+    if (this.reconnectAttempts >= this.config.maxReconnectAttempts) {
+      console.error('🔌 Max reconnect attempts reached, giving up');
+      return;
+    }
+
+    this.reconnectAttempts++;
+    console.log(
+      `🔌 Reconnecting in ${this.config.reconnectDelayMs}ms (attempt ${this.reconnectAttempts})`
+    );
+
+    this.reconnectTimeout = setTimeout(() => {
+      this.createConnection();
+    }, this.config.reconnectDelayMs);
+  }
+
+  /**
+   * Close the WebSocket connection.
+   */
+  close(): void {
+    this.isClosing = true;
+    this.stopPingInterval();
+
+    if (this.reconnectTimeout) {
+      clearTimeout(this.reconnectTimeout);
+      this.reconnectTimeout = null;
+    }
+
+    if (this.ws) {
+      this.ws.close();
+      this.ws = null;
+    }
+
+    console.log('🔌 WebSocket client closed');
+  }
+
+  /**
+   * Check if the client is connected.
+   */
+  isConnected(): boolean {
+    return this.ws?.readyState === WebSocket.OPEN;
+  }
+}
diff --git a/packages/core/src/websocket/index.ts b/packages/core/src/websocket/index.ts
index 77518d3..bfa3bda 100644
--- a/packages/core/src/websocket/index.ts
+++ b/packages/core/src/websocket/index.ts
@@ -11,6 +11,8 @@ export {
   type ClientSubscription,
 } from './server.js';
 
+export { UDLWebSocketClient, type WebSocketClientConfig } from './client.js';
+
 import { UDLWebSocketServer } from './server.js';
 
 /**

From 7efd9d44dacec8225d37398e94bb3b9d63eda06d Mon Sep 17 00:00:00 2001
From: dawidurbanski <hi@dawidurbanski.com>
Date: Mon, 22 Dec 2025 21:06:07 +0100
Subject: [PATCH 23/46] feat(core): add self-detection for shared remote sync
 config

When remote.url points to the same host:port as the local server,
UDL now detects this and loads plugins instead of syncing from remote.

This allows sharing the same config file between production and local
development - production will source from plugins while local dev
will sync from the remote production server.

Self-detection handles:
- Exact host:port matches
- Local host aliases (localhost, 127.0.0.1, 0.0.0.0)
---
 docs/content/7.deployment/4.remote-sync.md | 28 +++++++++++
 packages/core/src/index.ts                 |  1 +
 packages/core/src/start-server.ts          | 19 ++++++--
 packages/core/src/sync/index.ts            |  1 +
 packages/core/src/sync/remote.ts           | 54 ++++++++++++++++++++++
 5 files changed, 99 insertions(+), 4 deletions(-)

diff --git a/docs/content/7.deployment/4.remote-sync.md b/docs/content/7.deployment/4.remote-sync.md
index c1567f9..ca4695d 100644
--- a/docs/content/7.deployment/4.remote-sync.md
+++ b/docs/content/7.deployment/4.remote-sync.md
@@ -129,6 +129,34 @@ When `remote.url` is set, the local server:
 - **Keeps** local GraphQL endpoint active
 - **Keeps** local codegen working (if configured)
 
+### Shared Config Files
+
+You can use the same config file for both production and local development. UDL automatically detects when the remote URL points to itself:
+
+```typescript [udl.config.ts]
+export const config = defineConfig({
+  port: 4000,
+  plugins: ['./plugins/my-source'],
+  remote: {
+    url: 'http://localhost:4000',  // Same as local server
+  },
+});
+```
+
+**On production** (running on port 4000):
+- Detects that `remote.url` points to itself
+- Loads plugins and sources data normally
+- Logs: `📡 Remote URL points to self, loading plugins instead`
+
+**On local dev** (running on different port or machine):
+- Detects that `remote.url` points to a different server
+- Syncs from the remote production server
+- Logs: `📡 Remote mode: syncing from http://localhost:4000`
+
+Self-detection works for:
+- Same host and port (exact match)
+- Local aliases (`localhost`, `127.0.0.1`, `0.0.0.0` are treated as equivalent)
+
 ## Use Cases
 
 ### Local Development with Production Data
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 94fa8be..cf7313c 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -102,6 +102,7 @@ export {
   fetchRemoteNodes,
   tryConnectRemoteWebSocket,
   initRemoteSync,
+  isSelfUrl,
   type RemoteSyncConfig,
 } from './sync/index.js';
 
diff --git a/packages/core/src/start-server.ts b/packages/core/src/start-server.ts
index 52dc0a6..0561de0 100644
--- a/packages/core/src/start-server.ts
+++ b/packages/core/src/start-server.ts
@@ -25,7 +25,7 @@ import {
   setDefaultWebSocketServer,
   getDefaultWebSocketServer,
 } from '@/websocket/index.js';
-import { initRemoteSync } from '@/sync/remote.js';
+import { initRemoteSync, isSelfUrl } from '@/sync/remote.js';
 import type { UDLWebSocketClient } from '@/websocket/client.js';
 
 export interface StartServerOptions {
@@ -112,13 +112,24 @@ export async function startServer(options: StartServerOptions = {}) {
   let remoteWsClient: UDLWebSocketClient | null = null;
 
   // Check if we should sync from a remote UDL server
-  if (userConfig.remote?.url) {
+  // Skip remote sync if the URL points to ourselves (shared config between prod and local)
+  const remoteUrl = userConfig.remote?.url;
+  const shouldSyncFromRemote = remoteUrl && !isSelfUrl(remoteUrl, host, port);
+
+  if (remoteUrl && !shouldSyncFromRemote) {
+    // Remote URL points to ourselves - this is the production server
+    console.log(
+      `📡 Remote URL points to self (${remoteUrl}), loading plugins instead`
+    );
+  }
+
+  if (shouldSyncFromRemote) {
     // Remote mode: fetch data from remote UDL instead of loading plugins
-    console.log(`📡 Remote mode: syncing from ${userConfig.remote.url}`);
+    console.log(`📡 Remote mode: syncing from ${remoteUrl}`);
 
     remoteWsClient = await initRemoteSync(
       {
-        url: userConfig.remote.url,
+        url: remoteUrl,
         // Note: WebSocket client uses sensible defaults (5s reconnect, 30s ping)
         // Custom client config can be added to RemoteSyncConfig if needed
       },
diff --git a/packages/core/src/sync/index.ts b/packages/core/src/sync/index.ts
index 43a89c6..84d88fc 100644
--- a/packages/core/src/sync/index.ts
+++ b/packages/core/src/sync/index.ts
@@ -14,5 +14,6 @@ export {
   fetchRemoteNodes,
   tryConnectRemoteWebSocket,
   initRemoteSync,
+  isSelfUrl,
   type RemoteSyncConfig,
 } from './remote.js';
diff --git a/packages/core/src/sync/remote.ts b/packages/core/src/sync/remote.ts
index fe00c09..fe39cd5 100644
--- a/packages/core/src/sync/remote.ts
+++ b/packages/core/src/sync/remote.ts
@@ -5,6 +5,60 @@ import {
 } from '@/websocket/client.js';
 import type { SyncResponse } from '@/handlers/sync.js';
 
+/**
+ * Local host aliases that all refer to the same machine.
+ */
+const LOCAL_HOST_ALIASES = new Set(['localhost', '127.0.0.1', '0.0.0.0']);
+
+/**
+ * Check if a remote URL points to the current server.
+ *
+ * This is used to detect when the config file is shared between
+ * production and local development. If the remote URL points to
+ * ourselves, we should load plugins instead of syncing from remote.
+ *
+ * @param remoteUrl - The remote UDL URL from config
+ * @param localHost - The local server host
+ * @param localPort - The local server port
+ * @returns true if the remote URL points to this server
+ */
+export function isSelfUrl(
+  remoteUrl: string,
+  localHost: string,
+  localPort: number
+): boolean {
+  try {
+    const remote = new URL(remoteUrl);
+    const remotePort =
+      remote.port || (remote.protocol === 'https:' ? '443' : '80');
+
+    // Ports must match
+    if (String(localPort) !== String(remotePort)) {
+      return false;
+    }
+
+    const remoteHost = remote.hostname.toLowerCase();
+    const normalizedLocalHost = localHost.toLowerCase();
+
+    // Direct match
+    if (remoteHost === normalizedLocalHost) {
+      return true;
+    }
+
+    // Both are local aliases (localhost, 127.0.0.1, 0.0.0.0)
+    if (
+      LOCAL_HOST_ALIASES.has(remoteHost) &&
+      LOCAL_HOST_ALIASES.has(normalizedLocalHost)
+    ) {
+      return true;
+    }
+
+    return false;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Configuration for remote sync.
  */

From 576da3b017614ee463dd5aabc71ad72203e09c39 Mon Sep 17 00:00:00 2001
From: dawidurbanski <hi@dawidurbanski.com>
Date: Mon, 22 Dec 2025 21:24:44 +0100
Subject: [PATCH 24/46] fix(core): use reachability check for remote sync
 detection
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The previous approach compared host:port which didn't work for shared
configs where both production and local dev use the same URL.

New approach: check if the remote server is actually reachable.
- If reachable → sync from remote (we are local dev)
- If not reachable → load plugins (we are production)

This correctly handles:
- Same machine, same port (production starts first)
- Same machine, different ports
- Multi-tenant localhost setups
- Remote production servers
---
 docs/content/7.deployment/4.remote-sync.md | 43 ++++++++++-----
 packages/core/src/index.ts                 |  2 +-
 packages/core/src/start-server.ts          | 58 +++++++++++---------
 packages/core/src/sync/index.ts            |  2 +-
 packages/core/src/sync/remote.ts           | 61 +++++++---------------
 5 files changed, 84 insertions(+), 82 deletions(-)

diff --git a/docs/content/7.deployment/4.remote-sync.md b/docs/content/7.deployment/4.remote-sync.md
index ca4695d..b3b453c 100644
--- a/docs/content/7.deployment/4.remote-sync.md
+++ b/docs/content/7.deployment/4.remote-sync.md
@@ -131,31 +131,48 @@ When `remote.url` is set, the local server:
 
 ### Shared Config Files
 
-You can use the same config file for both production and local development. UDL automatically detects when the remote URL points to itself:
+You can use the same config file for both production and local development. UDL automatically detects which mode to use by checking if the remote server is reachable:
 
 ```typescript [udl.config.ts]
 export const config = defineConfig({
   port: 4000,
   plugins: ['./plugins/my-source'],
   remote: {
-    url: 'http://localhost:4000',  // Same as local server
+    url: 'http://localhost:4000',
   },
 });
 ```
 
-**On production** (running on port 4000):
-- Detects that `remote.url` points to itself
-- Loads plugins and sources data normally
-- Logs: `📡 Remote URL points to self, loading plugins instead`
+**When production starts first:**
 
-**On local dev** (running on different port or machine):
-- Detects that `remote.url` points to a different server
-- Syncs from the remote production server
-- Logs: `📡 Remote mode: syncing from http://localhost:4000`
+```
+Production                           Local Dev (not started yet)
+     │
+     │  Check: Is http://localhost:4000 reachable?
+     │  ❌ No (nothing running yet)
+     │
+     │  Load plugins, source data
+     │  Start server on :4000
+     │
+```
+
+**When local dev starts after:**
+
+```
+Production (running on :4000)        Local Dev
+                                          │
+                                          │  Check: Is http://localhost:4000 reachable?
+                                          │  ✅ Yes (production is running)
+                                          │
+                                          │  Sync from remote instead of loading plugins
+                                          │
+```
 
-Self-detection works for:
-- Same host and port (exact match)
-- Local aliases (`localhost`, `127.0.0.1`, `0.0.0.0` are treated as equivalent)
+This works for any setup:
+- Same machine, same port (production starts first)
+- Same machine, different ports
+- Different machines (local dev connects to remote production)
+- Multi-tenant setups on localhost
 
 ## Use Cases
 
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index cf7313c..489330b 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -102,7 +102,7 @@ export {
   fetchRemoteNodes,
   tryConnectRemoteWebSocket,
   initRemoteSync,
-  isSelfUrl,
+  isRemoteReachable,
   type RemoteSyncConfig,
 } from './sync/index.js';
 
diff --git a/packages/core/src/start-server.ts b/packages/core/src/start-server.ts
index 0561de0..590bad9 100644
--- a/packages/core/src/start-server.ts
+++ b/packages/core/src/start-server.ts
@@ -25,7 +25,7 @@ import {
   setDefaultWebSocketServer,
   getDefaultWebSocketServer,
 } from '@/websocket/index.js';
-import { initRemoteSync, isSelfUrl } from '@/sync/remote.js';
+import { initRemoteSync, isRemoteReachable } from '@/sync/remote.js';
 import type { UDLWebSocketClient } from '@/websocket/client.js';
 
 export interface StartServerOptions {
@@ -112,34 +112,42 @@ export async function startServer(options: StartServerOptions = {}) {
   let remoteWsClient: UDLWebSocketClient | null = null;
 
   // Check if we should sync from a remote UDL server
-  // Skip remote sync if the URL points to ourselves (shared config between prod and local)
+  // If remote.url is set, try to reach it first - if unreachable, we are production
   const remoteUrl = userConfig.remote?.url;
-  const shouldSyncFromRemote = remoteUrl && !isSelfUrl(remoteUrl, host, port);
+  let shouldSyncFromRemote = false;
+
+  if (remoteUrl) {
+    console.log(`📡 Checking if remote UDL is reachable: ${remoteUrl}`);
+    const remoteReachable = await isRemoteReachable(remoteUrl);
+
+    if (remoteReachable) {
+      shouldSyncFromRemote = true;
+      console.log(`📡 Remote mode: syncing from ${remoteUrl}`);
+
+      remoteWsClient = await initRemoteSync(
+        {
+          url: remoteUrl,
+          // Note: WebSocket client uses sensible defaults (5s reconnect, 30s ping)
+          // Custom client config can be added to RemoteSyncConfig if needed
+        },
+        defaultStore
+      );
 
-  if (remoteUrl && !shouldSyncFromRemote) {
-    // Remote URL points to ourselves - this is the production server
-    console.log(
-      `📡 Remote URL points to self (${remoteUrl}), loading plugins instead`
-    );
+      if (remoteWsClient) {
+        console.log('📡 Connected to remote WebSocket for real-time updates');
+      }
+    } else {
+      console.log(
+        `📡 Remote not reachable, loading plugins instead (we are production)`
+      );
+    }
   }
 
-  if (shouldSyncFromRemote) {
-    // Remote mode: fetch data from remote UDL instead of loading plugins
-    console.log(`📡 Remote mode: syncing from ${remoteUrl}`);
-
-    remoteWsClient = await initRemoteSync(
-      {
-        url: remoteUrl,
-        // Note: WebSocket client uses sensible defaults (5s reconnect, 30s ping)
-        // Custom client config can be added to RemoteSyncConfig if needed
-      },
-      defaultStore
-    );
-
-    if (remoteWsClient) {
-      console.log('📡 Connected to remote WebSocket for real-time updates');
-    }
-  } else if (userConfig.plugins && userConfig.plugins.length > 0) {
+  if (
+    !shouldSyncFromRemote &&
+    userConfig.plugins &&
+    userConfig.plugins.length > 0
+  ) {
     // Normal mode: load plugins and source nodes locally
     console.log('Loading plugins...');
     // Track plugin names before loading
diff --git a/packages/core/src/sync/index.ts b/packages/core/src/sync/index.ts
index 84d88fc..98ea824 100644
--- a/packages/core/src/sync/index.ts
+++ b/packages/core/src/sync/index.ts
@@ -14,6 +14,6 @@ export {
   fetchRemoteNodes,
   tryConnectRemoteWebSocket,
   initRemoteSync,
-  isSelfUrl,
+  isRemoteReachable,
   type RemoteSyncConfig,
 } from './remote.js';
diff --git a/packages/core/src/sync/remote.ts b/packages/core/src/sync/remote.ts
index fe39cd5..5fcbd1a 100644
--- a/packages/core/src/sync/remote.ts
+++ b/packages/core/src/sync/remote.ts
@@ -6,54 +6,31 @@ import {
 import type { SyncResponse } from '@/handlers/sync.js';
 
 /**
- * Local host aliases that all refer to the same machine.
- */
-const LOCAL_HOST_ALIASES = new Set(['localhost', '127.0.0.1', '0.0.0.0']);
-
-/**
- * Check if a remote URL points to the current server.
+ * Check if a remote UDL server is reachable.
  *
- * This is used to detect when the config file is shared between
- * production and local development. If the remote URL points to
- * ourselves, we should load plugins instead of syncing from remote.
+ * This is used to detect whether we should sync from remote or load
+ * plugins locally. If the remote is not reachable, we are likely the
+ * production server and should load plugins.
  *
- * @param remoteUrl - The remote UDL URL from config
- * @param localHost - The local server host
- * @param localPort - The local server port
- * @returns true if the remote URL points to this server
+ * @param remoteUrl - The remote UDL URL to check
+ * @param timeoutMs - Timeout in milliseconds (default: 2000)
+ * @returns true if the remote server is reachable
  */
-export function isSelfUrl(
+export async function isRemoteReachable(
   remoteUrl: string,
-  localHost: string,
-  localPort: number
-): boolean {
+  timeoutMs = 2000
+): Promise<boolean> {
   try {
-    const remote = new URL(remoteUrl);
-    const remotePort =
-      remote.port || (remote.protocol === 'https:' ? '443' : '80');
-
-    // Ports must match
-    if (String(localPort) !== String(remotePort)) {
-      return false;
-    }
-
-    const remoteHost = remote.hostname.toLowerCase();
-    const normalizedLocalHost = localHost.toLowerCase();
-
-    // Direct match
-    if (remoteHost === normalizedLocalHost) {
-      return true;
-    }
-
-    // Both are local aliases (localhost, 127.0.0.1, 0.0.0.0)
-    if (
-      LOCAL_HOST_ALIASES.has(remoteHost) &&
-      LOCAL_HOST_ALIASES.has(normalizedLocalHost)
-    ) {
-      return true;
-    }
+    const healthUrl = new URL('/health', remoteUrl);
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
 
-    return false;
+    const response = await fetch(healthUrl.toString(), {
+      signal: controller.signal,
+    });
+
+    clearTimeout(timeoutId);
+    return response.ok;
   } catch {
     return false;
   }

From 0d6d18a790861a853e16ca8a3feed3bef8287ad5 Mon Sep 17 00:00:00 2001
From: dawidurbanski <hi@dawidurbanski.com>
Date: Mon, 22 Dec 2025 23:45:23 +0100
Subject: [PATCH 25/46] refactor(core,adapter-nextjs): remove hardcoded default
 port values

Let the config file determine the default port instead of hardcoding
it in CLI args and adapter commands. Port flag is now only passed
when explicitly specified by the user.
---
 .changeset/remove-hardcoded-port-defaults.md  |  8 ++++++++
 packages/adapter-nextjs/src/commands/dev.ts   | 12 +++++-------
 packages/adapter-nextjs/src/commands/start.ts | 12 +++++-------
 packages/core/bin/cli.js                      |  1 -
 4 files changed, 18 insertions(+), 15 deletions(-)
 create mode 100644 .changeset/remove-hardcoded-port-defaults.md

diff --git a/.changeset/remove-hardcoded-port-defaults.md b/.changeset/remove-hardcoded-port-defaults.md
new file mode 100644
index 0000000..e5b7a1a
--- /dev/null
+++ b/.changeset/remove-hardcoded-port-defaults.md
@@ -0,0 +1,8 @@
+---
+'universal-data-layer': patch
+'@universal-data-layer/adapter-nextjs': patch
+---
+
+refactor: remove hardcoded default port values
+
+Removed hardcoded default port (4000) from CLI and adapter commands. The port is now only passed when explicitly specified by the user, allowing the config file to determine the default port value instead.
diff --git a/packages/adapter-nextjs/src/commands/dev.ts b/packages/adapter-nextjs/src/commands/dev.ts
index fe5a74a..2802d5c 100644
--- a/packages/adapter-nextjs/src/commands/dev.ts
+++ b/packages/adapter-nextjs/src/commands/dev.ts
@@ -10,7 +10,6 @@ const CYAN = '\x1b[36m';
 const MAGENTA = '\x1b[35m';
 const RESET = '\x1b[0m';
 
-const DEFAULT_UDL_PORT = 4000;
 const DEFAULT_NEXT_PORT = 3000;
 
 /**
@@ -32,7 +31,6 @@ export async function runDev(
   config?: RunDevConfig
 ): Promise<void> {
   const exit = config?.exit ?? ((code: number) => process.exit(code));
-  const udlPort = options.port ?? DEFAULT_UDL_PORT;
   const nextPort = options.nextPort ?? DEFAULT_NEXT_PORT;
 
   const processes: SpawnedProcess[] = [];
@@ -57,11 +55,11 @@ export async function runDev(
   process.on('SIGTERM', handleSignal);
 
   // Spawn UDL server
-  const udlProcess = spawnWithPrefix(
-    'npx',
-    ['universal-data-layer', '--port', String(udlPort)],
-    `${CYAN}[udl]${RESET}`
-  );
+  const udlArgs = ['universal-data-layer'];
+  if (options.port !== undefined) {
+    udlArgs.push('--port', String(options.port));
+  }
+  const udlProcess = spawnWithPrefix('npx', udlArgs, `${CYAN}[udl]${RESET}`);
   processes.push(udlProcess);
 
   // Spawn Next.js dev server
diff --git a/packages/adapter-nextjs/src/commands/start.ts b/packages/adapter-nextjs/src/commands/start.ts
index 840c4a6..7f16830 100644
--- a/packages/adapter-nextjs/src/commands/start.ts
+++ b/packages/adapter-nextjs/src/commands/start.ts
@@ -10,7 +10,6 @@ const CYAN = '\x1b[36m';
 const MAGENTA = '\x1b[35m';
 const RESET = '\x1b[0m';
 
-const DEFAULT_UDL_PORT = 4000;
 const DEFAULT_NEXT_PORT = 3000;
 
 /**
@@ -32,7 +31,6 @@ export async function runStart(
   config?: RunStartConfig
 ): Promise<void> {
   const exit = config?.exit ?? ((code: number) => process.exit(code));
-  const udlPort = options.port ?? DEFAULT_UDL_PORT;
   const nextPort = options.nextPort ?? DEFAULT_NEXT_PORT;
 
   const processes: SpawnedProcess[] = [];
@@ -57,11 +55,11 @@ export async function runStart(
   process.on('SIGTERM', handleSignal);
 
   // Spawn UDL server
-  const udlProcess = spawnWithPrefix(
-    'npx',
-    ['universal-data-layer', '--port', String(udlPort)],
-    `${CYAN}[udl]${RESET}`
-  );
+  const udlArgs = ['universal-data-layer'];
+  if (options.port !== undefined) {
+    udlArgs.push('--port', String(options.port));
+  }
+  const udlProcess = spawnWithPrefix('npx', udlArgs, `${CYAN}[udl]${RESET}`);
   processes.push(udlProcess);
 
   // Spawn Next.js production server
diff --git a/packages/core/bin/cli.js b/packages/core/bin/cli.js
index d8eca36..6a03f3f 100755
--- a/packages/core/bin/cli.js
+++ b/packages/core/bin/cli.js
@@ -10,7 +10,6 @@ const { values } = parseArgs({
     port: {
       type: 'string',
       short: 'p',
-      default: '4000',
     },
     help: {
       type: 'boolean',

From bb7499adaa8aa9a419dd3237f73864868963d07e Mon Sep 17 00:00:00 2001
From: dawidurbanski <hi@dawidurbanski.com>
Date: Tue, 23 Dec 2025 01:30:40 +0100
Subject: [PATCH 26/46] feat(core): add webhook registration API for plugins

Introduce a simplified webhook registration system that allows plugins
to register handlers at convention-based URLs (/_webhooks/{plugin}/sync).

- WebhookRegistry class with register/getHandler/has methods
- WebhookRegistration interface with handler, description, verifySignature
- SignatureVerifier type for optional request signature validation
- Default singleton registry with setDefaultWebhookRegistry for testing
---
 .changeset/add-webhook-registration-api.md    |  77 +++++--
 packages/core/src/index.ts                    |   7 +-
 packages/core/src/nodes/index.ts              |  19 --
 packages/core/src/webhooks/index.ts           |   9 +-
 packages/core/src/webhooks/registry.ts        | 123 +++--------
 packages/core/src/webhooks/types.ts           | 198 +++++++++--------
 .../core/tests/unit/webhooks/registry.test.ts | 204 ++++--------------
 7 files changed, 232 insertions(+), 405 deletions(-)

diff --git a/.changeset/add-webhook-registration-api.md b/.changeset/add-webhook-registration-api.md
index d7ec08d..8772344 100644
--- a/.changeset/add-webhook-registration-api.md
+++ b/.changeset/add-webhook-registration-api.md
@@ -2,34 +2,69 @@
 'universal-data-layer': minor
 ---
 
-Add plugin webhook registration API
+Add plugin webhook handler export API
 
-Extends `SourceNodesContext` with `registerWebhook` function, allowing plugins to register webhook handlers that will receive and process incoming webhook payloads from external data sources.
+Plugins can now export a `registerWebhookHandler` function to handle webhooks with custom logic. When exported, it replaces the default CRUD handler for the plugin's `/_webhooks/{plugin-name}/sync` endpoint.
 
 **Usage in plugins:**
 
 ```typescript
-export async function sourceNodes({ actions, registerWebhook }) {
-  // Source initial data...
-
-  registerWebhook({
-    path: 'entry-update',
-    handler: async (req, res, context) => {
-      const { body, actions } = context;
-      await actions.createNode(transformEntry(body), { ... });
-      res.writeHead(200);
-      res.end();
-    },
-    verifySignature: (req, body) => {
-      return verifyHmac(body, req.headers['x-signature'], secret);
-    },
-  });
+// Plugin's udl.config.ts
+import { defineConfig } from 'universal-data-layer';
+
+export const config = defineConfig({
+  name: 'my-cms-plugin',
+  type: 'source',
+});
+
+// Custom webhook handler replaces the default
+export async function registerWebhookHandler({ req, res, actions, body, store, rawBody }) {
+  // Verify signature using your CMS's method
+  const signature = req.headers['x-webhook-signature'];
+  if (!verifySignature(rawBody, signature)) {
+    res.writeHead(401);
+    res.end('Invalid signature');
+    return;
+  }
+
+  // Handle different event types
+  const eventType = req.headers['x-webhook-type'];
+
+  if (eventType === 'entry.publish') {
+    await actions.createNode(transformEntry(body), { ... });
+  } else if (eventType === 'entry.delete') {
+    await actions.deleteNode(body.sys.id);
+  }
+
+  res.writeHead(200);
+  res.end();
+}
+```
+
+**Key benefits:**
+
+- Clear separation: `sourceNodes` for sourcing, `registerWebhookHandler` for webhooks
+- Convention-based URL: always `/_webhooks/{plugin-name}/sync`
+- Plugin controls its own routing and signature verification internally
+- Replaces default handler - no confusion about which handler runs
+
+**Handler context:**
+
+The handler receives a flattened context object:
+
+```typescript
+interface PluginWebhookHandlerContext {
+  req: IncomingMessage; // The incoming HTTP request
+  res: ServerResponse; // The server response
+  actions: NodeActions; // Node CRUD operations
+  store: NodeStore; // Access to all nodes
+  body: unknown; // Parsed JSON body
+  rawBody: Buffer; // Raw body for signature verification
 }
 ```
 
 **New exports:**
 
-- `WebhookRegistry` - Central registry for webhook handlers
-- `WebhookRegistrationError` - Error thrown on invalid registration
-- `defaultWebhookRegistry` - Default singleton instance
-- `WebhookRegistration`, `WebhookHandler`, `WebhookHandlerFn`, `WebhookHandlerContext` types
+- `PluginWebhookHandler` - Type for the handler function
+- `PluginWebhookHandlerContext` - Type for the handler context
+- `registerPluginWebhookHandler` - Internal utility for registering custom handlers
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 489330b..fd7b05e 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -155,12 +155,13 @@ export {
   type WebhookHandler,
   // Default webhook handler
   type DefaultWebhookPayload,
-  type DefaultWebhookHandlerConfig,
-  type PluginDefaultWebhookConfig,
   createDefaultWebhookHandler,
   DEFAULT_WEBHOOK_PATH,
   registerDefaultWebhook,
-  registerDefaultWebhooks,
+  registerPluginWebhookHandler,
+  // Plugin webhook handler export types
+  type PluginWebhookHandler,
+  type PluginWebhookHandlerContext,
 } from './webhooks/index.js';
 
 // Re-export WebSocket server utilities
diff --git a/packages/core/src/nodes/index.ts b/packages/core/src/nodes/index.ts
index 60cb5cc..64d7997 100644
--- a/packages/core/src/nodes/index.ts
+++ b/packages/core/src/nodes/index.ts
@@ -49,7 +49,6 @@ export {
 
 // Context for sourceNodes hook
 import type { NodeActions } from './actions/index.js';
-import type { WebhookRegistration } from '@/webhooks/types.js';
 
 /**
  * Context passed to the sourceNodes lifecycle hook
@@ -70,22 +69,4 @@ export interface SourceNodesContext<T = Record<string, unknown>> {
    * This is the directory containing the udl.config.ts that loaded this plugin.
    */
   cacheDir?: string;
-  /**
-   * Register a webhook handler for this plugin.
-   * The webhook will be available at `/_webhooks/{pluginName}/{path}`.
-   *
-   * @example
-   * ```typescript
-   * registerWebhook({
-   *   path: 'entry-update',
-   *   handler: async (req, res, context) => {
-   *     const { body, actions } = context;
-   *     await actions.createNode(transformEntry(body), { ... });
-   *     res.writeHead(200);
-   *     res.end();
-   *   },
-   * });
-   * ```
-   */
-  registerWebhook: (webhook: WebhookRegistration) => void;
 }
diff --git a/packages/core/src/webhooks/index.ts b/packages/core/src/webhooks/index.ts
index 608fea4..c5cce0a 100644
--- a/packages/core/src/webhooks/index.ts
+++ b/packages/core/src/webhooks/index.ts
@@ -13,8 +13,8 @@ export type {
   WebhookHandlerContext,
   WebhookHandler,
   DefaultWebhookPayload,
-  DefaultWebhookHandlerConfig,
-  PluginDefaultWebhookConfig,
+  PluginWebhookHandler,
+  PluginWebhookHandlerContext,
 } from './types.js';
 
 // Registry
@@ -67,6 +67,9 @@ export type {
   OutboundWebhookConfig,
   OutboundWebhookPayload,
   OutboundWebhookResult,
+  WebhookItem,
+  TransformPayloadContext,
+  TransformPayload,
 } from './outbound.js';
 
 export { OutboundWebhookManager } from './outbound.js';
@@ -80,5 +83,5 @@ export {
 
 export {
   registerDefaultWebhook,
-  registerDefaultWebhooks,
+  registerPluginWebhookHandler,
 } from './register-default.js';
diff --git a/packages/core/src/webhooks/registry.ts b/packages/core/src/webhooks/registry.ts
index 9e13f4c..41e7ea4 100644
--- a/packages/core/src/webhooks/registry.ts
+++ b/packages/core/src/webhooks/registry.ts
@@ -2,23 +2,13 @@
  * Webhook Registry
  *
  * Central registry for webhook handlers from all plugins.
- * Stores registered webhooks and provides lookup for routing
- * incoming webhook requests to the appropriate handler.
+ * Each plugin has exactly one webhook handler at /_webhooks/{plugin-name}/sync.
  */
 
 import type { WebhookRegistration, WebhookHandler } from './types.js';
 
 /**
- * Regular expression for validating webhook paths.
- * Paths must:
- * - Not start with a slash
- * - Contain only alphanumeric characters, hyphens, and underscores
- * - Not be empty
- */
-const PATH_REGEX = /^[a-zA-Z0-9][a-zA-Z0-9_-]*$/;
-
-/**
- * Error thrown when webhook registration fails validation.
+ * Error thrown when webhook registration fails.
  */
 export class WebhookRegistrationError extends Error {
   constructor(message: string) {
@@ -30,88 +20,48 @@ export class WebhookRegistrationError extends Error {
 /**
  * Central registry for webhook handlers.
  *
- * Plugins register their webhook handlers and the registry
- * provides lookup for routing incoming requests.
+ * Plugins register their webhook handler and the registry
+ * provides lookup for routing incoming requests. Each plugin
+ * can only have one handler (at the convention-based path /sync).
  *
  * @example
  * ```typescript
  * const registry = new WebhookRegistry();
  *
- * // Register a webhook
+ * // Register a webhook handler
  * registry.register('my-plugin', {
- *   path: 'entry-update',
  *   handler: async (req, res, context) => { ... },
+ *   description: 'My plugin handler',
  * });
  *
  * // Look up a handler
- * const handler = registry.getHandler('my-plugin', 'entry-update');
+ * const handler = registry.getHandler('my-plugin');
  * ```
  */
 export class WebhookRegistry {
   private handlers: Map<string, WebhookHandler> = new Map();
 
-  /**
-   * Generate the map key for a webhook handler.
-   * @param pluginName - The plugin that registered the webhook
-   * @param path - The webhook path
-   * @returns The map key in format "pluginName/path"
-   */
-  private getKey(pluginName: string, path: string): string {
-    return `${pluginName}/${path}`;
-  }
-
-  /**
-   * Validate a webhook path.
-   * @param path - The path to validate
-   * @throws {WebhookRegistrationError} If the path is invalid
-   */
-  private validatePath(path: string): void {
-    if (!path) {
-      throw new WebhookRegistrationError('Webhook path cannot be empty');
-    }
-
-    if (path.startsWith('/')) {
-      throw new WebhookRegistrationError(
-        `Webhook path cannot start with '/': ${path}`
-      );
-    }
-
-    if (!PATH_REGEX.test(path)) {
-      throw new WebhookRegistrationError(
-        `Webhook path contains invalid characters: ${path}. ` +
-          'Path must contain only alphanumeric characters, hyphens, and underscores, ' +
-          'and must start with an alphanumeric character.'
-      );
-    }
-  }
-
   /**
    * Register a webhook handler for a plugin.
    *
    * @param pluginName - The name of the plugin registering the webhook
    * @param webhook - The webhook registration configuration
-   * @throws {WebhookRegistrationError} If the path is invalid or already registered
+   * @throws {WebhookRegistrationError} If a handler is already registered for this plugin
    *
    * @example
    * ```typescript
-   * registry.register('@my-org/plugin-source-cms', {
-   *   path: 'content-update',
+   * registry.register('my-plugin', {
    *   handler: async (req, res, context) => {
    *     // Handle webhook
    *   },
-   *   verifySignature: (req, body) => verifyHmac(body, req.headers['x-signature']),
-   *   description: 'Handles content update events',
+   *   description: 'Handles webhook events',
    * });
    * ```
    */
   register(pluginName: string, webhook: WebhookRegistration): void {
-    this.validatePath(webhook.path);
-
-    const key = this.getKey(pluginName, webhook.path);
-
-    if (this.handlers.has(key)) {
+    if (this.handlers.has(pluginName)) {
       throw new WebhookRegistrationError(
-        `Webhook path '${webhook.path}' is already registered for plugin '${pluginName}'`
+        `Webhook handler is already registered for plugin '${pluginName}'`
       );
     }
 
@@ -120,39 +70,35 @@ export class WebhookRegistry {
       pluginName,
     };
 
-    this.handlers.set(key, handler);
+    this.handlers.set(pluginName, handler);
   }
 
   /**
-   * Get a webhook handler by plugin name and path.
+   * Get a webhook handler by plugin name.
    *
    * @param pluginName - The plugin that registered the webhook
-   * @param path - The webhook path
    * @returns The webhook handler, or undefined if not found
    *
    * @example
    * ```typescript
-   * const handler = registry.getHandler('my-plugin', 'entry-update');
+   * const handler = registry.getHandler('my-plugin');
    * if (handler) {
    *   await handler.handler(req, res, context);
    * }
    * ```
    */
-  getHandler(pluginName: string, path: string): WebhookHandler | undefined {
-    const key = this.getKey(pluginName, path);
-    return this.handlers.get(key);
+  getHandler(pluginName: string): WebhookHandler | undefined {
+    return this.handlers.get(pluginName);
   }
 
   /**
-   * Check if a webhook handler exists.
+   * Check if a webhook handler exists for a plugin.
    *
    * @param pluginName - The plugin name
-   * @param path - The webhook path
    * @returns True if the handler exists
    */
-  has(pluginName: string, path: string): boolean {
-    const key = this.getKey(pluginName, path);
-    return this.handlers.has(key);
+  has(pluginName: string): boolean {
+    return this.handlers.has(pluginName);
   }
 
   /**
@@ -163,42 +109,21 @@ export class WebhookRegistry {
    * @example
    * ```typescript
    * const allHandlers = registry.getAllHandlers();
-   * console.log(`${allHandlers.length} webhooks registered`);
+   * console.log(`${allHandlers.length} webhook handlers registered`);
    * ```
    */
   getAllHandlers(): WebhookHandler[] {
     return Array.from(this.handlers.values());
   }
 
-  /**
-   * Get all webhook handlers registered by a specific plugin.
-   *
-   * @param pluginName - The plugin name to filter by
-   * @returns Array of webhook handlers for the specified plugin
-   *
-   * @example
-   * ```typescript
-   * const contentfulWebhooks = registry.getHandlersByPlugin(
-   *   '@universal-data-layer/plugin-source-contentful'
-   * );
-   * ```
-   */
-  getHandlersByPlugin(pluginName: string): WebhookHandler[] {
-    return Array.from(this.handlers.values()).filter(
-      (handler) => handler.pluginName === pluginName
-    );
-  }
-
   /**
    * Remove a webhook handler.
    *
    * @param pluginName - The plugin name
-   * @param path - The webhook path
    * @returns True if a handler was removed, false if it didn't exist
    */
-  unregister(pluginName: string, path: string): boolean {
-    const key = this.getKey(pluginName, path);
-    return this.handlers.delete(key);
+  unregister(pluginName: string): boolean {
+    return this.handlers.delete(pluginName);
   }
 
   /**
diff --git a/packages/core/src/webhooks/types.ts b/packages/core/src/webhooks/types.ts
index dbcd7a8..a723587 100644
--- a/packages/core/src/webhooks/types.ts
+++ b/packages/core/src/webhooks/types.ts
@@ -47,46 +47,36 @@ export type WebhookHandlerFn = (
   context: WebhookHandlerContext
 ) => Promise<void>;
 
+/**
+ * Signature verification function type.
+ * Returns true if the signature is valid, false otherwise.
+ */
+export type SignatureVerifier = (
+  req: IncomingMessage,
+  rawBody: Buffer
+) => boolean | Promise<boolean>;
+
 /**
  * Configuration for registering a webhook handler.
  *
- * Plugins provide this configuration when calling `registerWebhook()` in
- * their `sourceNodes` hook. The path is combined with the plugin name to
- * create the full webhook URL.
+ * Simplified registration that only requires the handler function.
+ * All webhooks are registered at the convention-based path:
+ * `/_webhooks/{pluginName}/sync`
  *
  * @example
  * ```typescript
- * // In plugin's sourceNodes hook
- * registerWebhook({
- *   path: 'entry-update',
- *   description: 'Handles Contentful entry publish/unpublish events',
+ * // Internal registration
+ * registry.register('my-plugin', {
  *   handler: async (req, res, context) => {
- *     const { body, actions } = context;
- *     // Process webhook payload and update nodes
  *     await actions.createNode(transformEntry(body), { ... });
- *     res.writeHead(200, { 'Content-Type': 'application/json' });
- *     res.end(JSON.stringify({ received: true }));
- *   },
- *   verifySignature: (req, body) => {
- *     const signature = req.headers['x-contentful-signature'];
- *     return verifyHmac(body, signature, secret);
+ *     res.writeHead(200);
+ *     res.end();
  *   },
+ *   description: 'Default UDL sync handler',
  * });
  * ```
  */
 export interface WebhookRegistration {
-  /**
-   * Path suffix for the webhook endpoint.
-   * Combined with plugin name to form full path: `/_webhooks/{pluginName}/{path}`
-   *
-   * Must not start with `/` and can only contain alphanumeric characters,
-   * hyphens, and underscores.
-   *
-   * @example 'entry-update'
-   * @example 'product_sync'
-   */
-  path: string;
-
   /**
    * Handler function to process incoming webhook payloads.
    * Receives raw request/response objects and a context with node store access.
@@ -94,24 +84,25 @@ export interface WebhookRegistration {
   handler: WebhookHandlerFn;
 
   /**
-   * Optional function to verify webhook signatures.
-   * Called before the handler to validate the request authenticity.
-   * Return `true` if signature is valid, `false` to reject the request.
-   *
-   * @param req - The incoming HTTP request with headers
-   * @param body - Raw body buffer for computing signatures
-   * @returns Whether the signature is valid
+   * Optional description for logging and debugging purposes.
+   * @example 'Default UDL sync handler for my-plugin'
    */
-  verifySignature?: (
-    req: IncomingMessage,
-    body: Buffer
-  ) => boolean | Promise<boolean>;
+  description?: string;
 
   /**
-   * Optional description for logging and debugging purposes.
-   * @example 'Handles Contentful entry publish/unpublish events'
+   * Optional signature verification function.
+   * If provided, webhooks will be rejected with 401 if verification fails.
+   * Called before the webhook is queued for processing.
+   *
+   * @example
+   * ```typescript
+   * verifySignature: (req, rawBody) => {
+   *   const signature = req.headers['x-webhook-signature'];
+   *   return verifyHmac(rawBody, signature, secret);
+   * }
+   * ```
    */
-  description?: string;
+  verifySignature?: SignatureVerifier;
 }
 
 /**
@@ -123,6 +114,77 @@ export interface WebhookHandler extends WebhookRegistration {
   pluginName: string;
 }
 
+/**
+ * Context passed to plugin's `registerWebhookHandler` export.
+ *
+ * This is a flattened context that combines request, response, and node operations
+ * into a single object for convenience.
+ *
+ * @example
+ * ```typescript
+ * // In plugin's udl.config.ts
+ * export async function registerWebhookHandler({ req, res, actions, body }) {
+ *   const eventType = req.headers['x-webhook-type'];
+ *
+ *   if (eventType === 'entry.publish') {
+ *     await actions.createNode(transformEntry(body), { ... });
+ *   } else if (eventType === 'entry.delete') {
+ *     await actions.deleteNode(body.sys.id);
+ *   }
+ *
+ *   res.writeHead(200);
+ *   res.end();
+ * }
+ * ```
+ */
+export interface PluginWebhookHandlerContext {
+  /** The incoming HTTP request */
+  req: IncomingMessage;
+  /** The server response */
+  res: ServerResponse;
+  /** Bound node actions for creating, updating, or deleting nodes */
+  actions: NodeActions;
+  /** Access to the node store for querying existing nodes */
+  store: NodeStore;
+  /** Parsed JSON body (if content-type is application/json), otherwise undefined */
+  body: unknown;
+  /** Raw body buffer for signature verification */
+  rawBody: Buffer;
+}
+
+/**
+ * Function signature for plugin's `registerWebhookHandler` export.
+ *
+ * Plugins can export this function to handle webhooks with custom logic.
+ * When exported, it replaces the default CRUD handler for the plugin's
+ * `/_webhooks/{plugin-name}/sync` endpoint.
+ *
+ * @example
+ * ```typescript
+ * // Plugin's udl.config.ts
+ * export async function registerWebhookHandler({ req, res, actions, body }) {
+ *   // Verify signature using your CMS's method
+ *   if (!verifySignature(req, body)) {
+ *     res.writeHead(401);
+ *     res.end('Invalid signature');
+ *     return;
+ *   }
+ *
+ *   // Handle different event types
+ *   const eventType = req.headers['x-webhook-type'];
+ *   if (eventType === 'entry.publish') {
+ *     await actions.createNode(transformEntry(body), { ... });
+ *   }
+ *
+ *   res.writeHead(200);
+ *   res.end();
+ * }
+ * ```
+ */
+export type PluginWebhookHandler = (
+  context: PluginWebhookHandlerContext
+) => Promise<void>;
+
 /**
  * Standardized webhook payload for default handlers.
  * This payload format is used by the auto-registered default webhook handlers.
@@ -153,57 +215,3 @@ export interface DefaultWebhookPayload {
    */
   data?: Record<string, unknown>;
 }
-
-/**
- * Per-plugin configuration for default webhook handler.
- */
-export interface PluginDefaultWebhookConfig {
-  /**
-   * Custom path for this plugin's default webhook.
-   * If not specified, uses the global default path.
-   */
-  path?: string;
-}
-
-/**
- * Configuration for the default webhook handler feature.
- * When enabled, automatically registers a standardized webhook endpoint
- * for each loaded plugin that has an `idField` configured.
- *
- * The webhook handler uses the plugin's `idField` config to look up existing
- * nodes when processing update/delete operations.
- *
- * @example
- * ```typescript
- * defineConfig({
- *   defaultWebhook: {
- *     enabled: true,
- *     path: 'sync',
- *     plugins: {
- *       'contentful': { path: 'content-sync' },
- *       'legacy-plugin': false,  // Disable for this plugin
- *     },
- *   },
- * });
- * ```
- */
-export interface DefaultWebhookHandlerConfig {
-  /**
-   * Whether default handlers are enabled.
-   * @default true (when this config object is present)
-   */
-  enabled?: boolean;
-
-  /**
-   * The default path for all plugin webhooks.
-   * @default 'sync'
-   */
-  path?: string;
-
-  /**
-   * Per-plugin configuration overrides.
-   * Set to `false` to disable default handler for a specific plugin.
-   * Set to `{ path: 'custom' }` to use a custom path for that plugin.
-   */
-  plugins?: Record<string, PluginDefaultWebhookConfig | false>;
-}
diff --git a/packages/core/tests/unit/webhooks/registry.test.ts b/packages/core/tests/unit/webhooks/registry.test.ts
index ab5a658..b0f9603 100644
--- a/packages/core/tests/unit/webhooks/registry.test.ts
+++ b/packages/core/tests/unit/webhooks/registry.test.ts
@@ -10,12 +10,8 @@ import {
 import type { IncomingMessage, ServerResponse } from 'node:http';
 
 // Sample webhook handler for testing
-const createTestWebhook = (
-  path: string,
-  description?: string
-): WebhookRegistration => {
+const createTestWebhook = (description?: string): WebhookRegistration => {
   const webhook: WebhookRegistration = {
-    path,
     handler: async (
       _req: IncomingMessage,
       res: ServerResponse,
@@ -31,22 +27,6 @@ const createTestWebhook = (
   return webhook;
 };
 
-// Sample webhook with signature verification
-const createWebhookWithSignature = (path: string): WebhookRegistration => ({
-  path,
-  handler: async (
-    _req: IncomingMessage,
-    res: ServerResponse,
-    _context: WebhookHandlerContext
-  ) => {
-    res.writeHead(200);
-    res.end('OK');
-  },
-  verifySignature: (_req: IncomingMessage, _body: Buffer) => {
-    return true;
-  },
-});
-
 describe('WebhookRegistry', () => {
   let registry: WebhookRegistry;
 
@@ -56,50 +36,40 @@ describe('WebhookRegistry', () => {
 
   describe('register', () => {
     it('should register a webhook handler', () => {
-      const webhook = createTestWebhook('entry-update', 'Handle entry updates');
+      const webhook = createTestWebhook('Handle entry updates');
 
       registry.register('test-plugin', webhook);
 
-      const handler = registry.getHandler('test-plugin', 'entry-update');
+      const handler = registry.getHandler('test-plugin');
       expect(handler).toBeDefined();
-      expect(handler?.path).toBe('entry-update');
       expect(handler?.pluginName).toBe('test-plugin');
       expect(handler?.description).toBe('Handle entry updates');
     });
 
     it('should preserve the handler function', () => {
-      const webhook = createTestWebhook('test-path');
+      const webhook = createTestWebhook();
 
       registry.register('test-plugin', webhook);
 
-      const handler = registry.getHandler('test-plugin', 'test-path');
+      const handler = registry.getHandler('test-plugin');
       expect(handler?.handler).toBe(webhook.handler);
     });
 
-    it('should preserve optional verifySignature function', () => {
-      const webhook = createWebhookWithSignature('signed-webhook');
-
-      registry.register('test-plugin', webhook);
-
-      const handler = registry.getHandler('test-plugin', 'signed-webhook');
-      expect(handler?.verifySignature).toBe(webhook.verifySignature);
-    });
-
-    it('should allow same path for different plugins', () => {
-      const webhook1 = createTestWebhook('update');
-      const webhook2 = createTestWebhook('update');
+    it('should allow registration for different plugins', () => {
+      const webhook1 = createTestWebhook('Plugin A handler');
+      const webhook2 = createTestWebhook('Plugin B handler');
 
       registry.register('plugin-a', webhook1);
       registry.register('plugin-b', webhook2);
 
-      expect(registry.getHandler('plugin-a', 'update')).toBeDefined();
-      expect(registry.getHandler('plugin-b', 'update')).toBeDefined();
+      expect(registry.getHandler('plugin-a')).toBeDefined();
+      expect(registry.getHandler('plugin-b')).toBeDefined();
       expect(registry.size()).toBe(2);
     });
 
-    it('should throw error for duplicate path within same plugin', () => {
-      const webhook1 = createTestWebhook('duplicate');
-      const webhook2 = createTestWebhook('duplicate');
+    it('should throw error for duplicate registration for same plugin', () => {
+      const webhook1 = createTestWebhook();
+      const webhook2 = createTestWebhook();
 
       registry.register('test-plugin', webhook1);
 
@@ -107,114 +77,40 @@ describe('WebhookRegistry', () => {
         WebhookRegistrationError
       );
       expect(() => registry.register('test-plugin', webhook2)).toThrow(
-        "Webhook path 'duplicate' is already registered for plugin 'test-plugin'"
+        "Webhook handler is already registered for plugin 'test-plugin'"
       );
     });
   });
 
-  describe('path validation', () => {
-    it('should accept valid paths with alphanumeric characters', () => {
-      expect(() =>
-        registry.register('test', createTestWebhook('valid123'))
-      ).not.toThrow();
-    });
-
-    it('should accept valid paths with hyphens', () => {
-      expect(() =>
-        registry.register('test', createTestWebhook('entry-update'))
-      ).not.toThrow();
-    });
-
-    it('should accept valid paths with underscores', () => {
-      expect(() =>
-        registry.register('test', createTestWebhook('entry_update'))
-      ).not.toThrow();
-    });
-
-    it('should accept valid paths with mixed characters', () => {
-      expect(() =>
-        registry.register('test', createTestWebhook('v1-entry_update'))
-      ).not.toThrow();
-    });
-
-    it('should reject empty paths', () => {
-      expect(() => registry.register('test', createTestWebhook(''))).toThrow(
-        WebhookRegistrationError
-      );
-      expect(() => registry.register('test', createTestWebhook(''))).toThrow(
-        'Webhook path cannot be empty'
-      );
-    });
-
-    it('should reject paths starting with slash', () => {
-      expect(() =>
-        registry.register('test', createTestWebhook('/entry-update'))
-      ).toThrow(WebhookRegistrationError);
-      expect(() =>
-        registry.register('test', createTestWebhook('/entry-update'))
-      ).toThrow("Webhook path cannot start with '/'");
-    });
-
-    it('should reject paths with invalid characters', () => {
-      expect(() =>
-        registry.register('test', createTestWebhook('entry.update'))
-      ).toThrow(WebhookRegistrationError);
-      expect(() =>
-        registry.register('test', createTestWebhook('entry@update'))
-      ).toThrow(WebhookRegistrationError);
-      expect(() =>
-        registry.register('test', createTestWebhook('entry update'))
-      ).toThrow(WebhookRegistrationError);
-    });
-
-    it('should reject paths starting with hyphen', () => {
-      expect(() =>
-        registry.register('test', createTestWebhook('-entry'))
-      ).toThrow(WebhookRegistrationError);
-    });
-
-    it('should reject paths starting with underscore', () => {
-      expect(() =>
-        registry.register('test', createTestWebhook('_entry'))
-      ).toThrow(WebhookRegistrationError);
-    });
-  });
-
   describe('getHandler', () => {
-    it('should return handler for existing plugin+path', () => {
-      registry.register('my-plugin', createTestWebhook('webhook-path'));
+    it('should return handler for existing plugin', () => {
+      registry.register('my-plugin', createTestWebhook());
 
-      const handler = registry.getHandler('my-plugin', 'webhook-path');
+      const handler = registry.getHandler('my-plugin');
       expect(handler).toBeDefined();
       expect(handler?.pluginName).toBe('my-plugin');
     });
 
     it('should return undefined for non-existent handler', () => {
-      expect(registry.getHandler('non-existent', 'path')).toBeUndefined();
+      expect(registry.getHandler('non-existent')).toBeUndefined();
     });
 
     it('should return undefined for wrong plugin name', () => {
-      registry.register('plugin-a', createTestWebhook('path'));
-
-      expect(registry.getHandler('plugin-b', 'path')).toBeUndefined();
-    });
+      registry.register('plugin-a', createTestWebhook());
 
-    it('should return undefined for wrong path', () => {
-      registry.register('plugin', createTestWebhook('path-a'));
-
-      expect(registry.getHandler('plugin', 'path-b')).toBeUndefined();
+      expect(registry.getHandler('plugin-b')).toBeUndefined();
     });
   });
 
   describe('has', () => {
     it('should return true for existing handler', () => {
-      registry.register('plugin', createTestWebhook('path'));
+      registry.register('plugin', createTestWebhook());
 
-      expect(registry.has('plugin', 'path')).toBe(true);
+      expect(registry.has('plugin')).toBe(true);
     });
 
     it('should return false for non-existent handler', () => {
-      expect(registry.has('plugin', 'path')).toBe(false);
+      expect(registry.has('plugin')).toBe(false);
     });
   });
 
@@ -224,56 +120,34 @@ describe('WebhookRegistry', () => {
     });
 
     it('should return all registered handlers', () => {
-      registry.register('plugin-a', createTestWebhook('path-1'));
-      registry.register('plugin-a', createTestWebhook('path-2'));
-      registry.register('plugin-b', createTestWebhook('path-1'));
+      registry.register('plugin-a', createTestWebhook());
+      registry.register('plugin-b', createTestWebhook());
+      registry.register('plugin-c', createTestWebhook());
 
       const handlers = registry.getAllHandlers();
       expect(handlers).toHaveLength(3);
     });
 
     it('should include pluginName in returned handlers', () => {
-      registry.register('my-plugin', createTestWebhook('my-path'));
+      registry.register('my-plugin', createTestWebhook());
 
       const handlers = registry.getAllHandlers();
       expect(handlers[0]?.pluginName).toBe('my-plugin');
-      expect(handlers[0]?.path).toBe('my-path');
-    });
-  });
-
-  describe('getHandlersByPlugin', () => {
-    beforeEach(() => {
-      registry.register('plugin-a', createTestWebhook('path-1'));
-      registry.register('plugin-a', createTestWebhook('path-2'));
-      registry.register('plugin-b', createTestWebhook('path-3'));
-    });
-
-    it('should return only handlers for specified plugin', () => {
-      const handlers = registry.getHandlersByPlugin('plugin-a');
-
-      expect(handlers).toHaveLength(2);
-      expect(handlers.every((h) => h.pluginName === 'plugin-a')).toBe(true);
-    });
-
-    it('should return empty array for plugin with no handlers', () => {
-      const handlers = registry.getHandlersByPlugin('non-existent');
-
-      expect(handlers).toEqual([]);
     });
   });
 
   describe('unregister', () => {
     it('should remove a registered handler', () => {
-      registry.register('plugin', createTestWebhook('path'));
+      registry.register('plugin', createTestWebhook());
 
-      const result = registry.unregister('plugin', 'path');
+      const result = registry.unregister('plugin');
 
       expect(result).toBe(true);
-      expect(registry.getHandler('plugin', 'path')).toBeUndefined();
+      expect(registry.getHandler('plugin')).toBeUndefined();
     });
 
     it('should return false when handler does not exist', () => {
-      const result = registry.unregister('non-existent', 'path');
+      const result = registry.unregister('non-existent');
 
       expect(result).toBe(false);
     });
@@ -281,8 +155,8 @@ describe('WebhookRegistry', () => {
 
   describe('clear', () => {
     it('should remove all handlers', () => {
-      registry.register('plugin-a', createTestWebhook('path-1'));
-      registry.register('plugin-b', createTestWebhook('path-2'));
+      registry.register('plugin-a', createTestWebhook());
+      registry.register('plugin-b', createTestWebhook());
 
       registry.clear();
 
@@ -297,17 +171,17 @@ describe('WebhookRegistry', () => {
     });
 
     it('should return correct count after registrations', () => {
-      registry.register('plugin', createTestWebhook('path-1'));
-      registry.register('plugin', createTestWebhook('path-2'));
+      registry.register('plugin-a', createTestWebhook());
+      registry.register('plugin-b', createTestWebhook());
 
       expect(registry.size()).toBe(2);
     });
 
     it('should update after unregister', () => {
-      registry.register('plugin', createTestWebhook('path'));
+      registry.register('plugin', createTestWebhook());
       expect(registry.size()).toBe(1);
 
-      registry.unregister('plugin', 'path');
+      registry.unregister('plugin');
       expect(registry.size()).toBe(0);
     });
   });
@@ -325,10 +199,10 @@ describe('defaultWebhookRegistry singleton', () => {
 
   it('should be replaceable via setDefaultWebhookRegistry', () => {
     const newRegistry = new WebhookRegistry();
-    newRegistry.register('test', createTestWebhook('test-path'));
+    newRegistry.register('test', createTestWebhook());
 
     setDefaultWebhookRegistry(newRegistry);
 
-    expect(defaultWebhookRegistry.has('test', 'test-path')).toBe(true);
+    expect(defaultWebhookRegistry.has('test')).toBe(true);
   });
 });

From a203ae1b9f8b28e5d2a7a2d9bb58117c0a6ade8e Mon Sep 17 00:00:00 2001
From: dawidurbanski <hi@dawidurbanski.com>
Date: Tue, 23 Dec 2025 01:30:52 +0100
Subject: [PATCH 27/46] feat(core): add convention-based webhook HTTP routing

Route webhooks to handlers using convention-based URLs:
POST /_webhooks/{plugin-name}/sync

- isWebhookRequest() and getPluginFromWebhookUrl() for URL parsing
- Signature verification before queuing (returns 401 if invalid)
- JSON body parsing with 400 error for invalid JSON
- Request body collection with 1MB limit
- Integration tests for full webhook routing flow
---
 .changeset/add-webhook-http-routing.md        |  25 +-
 packages/core/src/handlers/webhook.ts         |  64 ++--
 .../tests/integration/webhook-routing.test.ts |  67 ++--
 .../core/tests/unit/handlers/webhook.test.ts  | 290 +++++-------------
 4 files changed, 131 insertions(+), 315 deletions(-)

diff --git a/.changeset/add-webhook-http-routing.md b/.changeset/add-webhook-http-routing.md
index 854ea6c..3befec5 100644
--- a/.changeset/add-webhook-http-routing.md
+++ b/.changeset/add-webhook-http-routing.md
@@ -2,35 +2,36 @@
 'universal-data-layer': minor
 ---
 
-Add webhook HTTP routing for incoming webhooks
+Add webhook HTTP routing with convention-based URL pattern
 
-Routes incoming webhook requests to the appropriate plugin handler based on the URL path `POST /_webhooks/{pluginName}/{path}`.
+Routes incoming webhook requests to the appropriate plugin handler using a fixed URL pattern `POST /_webhooks/{pluginName}/sync`.
 
 **Features:**
 
-- Routes webhooks to correct handler based on plugin name and path
+- Convention-based routing: all webhooks use the `/sync` path
+- Routes webhooks to correct handler based on plugin name
 - Validates HTTP method (only POST allowed)
-- Collects raw request body for signature verification
+- Collects raw request body for handler processing
 - Parses JSON body when content-type is `application/json`
 - Provides `WebhookHandlerContext` with store, actions, rawBody, and body
 - Enforces 1MB body size limit to prevent abuse
-- Returns appropriate HTTP status codes (405, 404, 401, 400, 500)
-- Logs webhook activity for debugging
+- Returns appropriate HTTP status codes (405, 404, 400, 413)
+- Queues webhooks for batch processing with debounce
 
 **URL Format:**
 
 ```
-POST /_webhooks/{plugin-name}/{webhook-path}
+POST /_webhooks/{plugin-name}/sync
 
 Examples:
-POST /_webhooks/contentful/entry-update
-POST /_webhooks/shopify/product-update
-POST /_webhooks/custom-plugin/sync
+POST /_webhooks/contentful/sync
+POST /_webhooks/shopify/sync
+POST /_webhooks/my-plugin/sync
 ```
 
-**New exports:**
+**Exports:**
 
 - `isWebhookRequest` - Check if URL is a webhook request
-- `parseWebhookUrl` - Parse plugin name and path from URL
+- `getPluginFromWebhookUrl` - Extract plugin name from webhook URL
 - `webhookHandler` - HTTP handler for webhook requests
 - `WEBHOOK_PATH_PREFIX` - URL prefix constant (`/_webhooks/`)
diff --git a/packages/core/src/handlers/webhook.ts b/packages/core/src/handlers/webhook.ts
index 557186b..e30300b 100644
--- a/packages/core/src/handlers/webhook.ts
+++ b/packages/core/src/handlers/webhook.ts
@@ -2,7 +2,7 @@
  * Webhook HTTP Handler
  *
  * Routes incoming webhook requests to the appropriate plugin handler.
- * URL format: POST /_webhooks/{pluginName}/{path}
+ * URL format: POST /_webhooks/{pluginName}/sync
  *
  * Webhooks are queued and processed in batches after a debounce period.
  * This prevents N rapid webhooks from triggering N separate processing cycles.
@@ -20,6 +20,9 @@ import { defaultStore } from '@/nodes/defaultStore.js';
 /** URL path prefix for webhook endpoints */
 export const WEBHOOK_PATH_PREFIX = '/_webhooks/';
 
+/** Pattern for webhook URLs: /_webhooks/{plugin-name}/sync */
+const WEBHOOK_PATTERN = /^\/_webhooks\/([^/]+)\/sync(?:\?.*)?$/;
+
 /** Maximum request body size (1MB) */
 const MAX_BODY_SIZE = 1024 * 1024;
 
@@ -34,32 +37,17 @@ export function isWebhookRequest(url: string): boolean {
 }
 
 /**
- * Parse the webhook URL to extract plugin name and path.
+ * Extract the plugin name from a webhook URL.
  *
- * @param url - The full request URL (e.g., "/_webhooks/contentful/entry-update")
- * @returns Object with pluginName and webhookPath, or null if invalid
+ * @param url - The full request URL (e.g., "/_webhooks/contentful/sync")
+ * @returns The plugin name, or null if invalid format
  */
-export function parseWebhookUrl(
-  url: string
-): { pluginName: string; webhookPath: string } | null {
-  if (!isWebhookRequest(url)) {
-    return null;
-  }
-
-  // Remove prefix and any query string
-  const urlPath = url.slice(WEBHOOK_PATH_PREFIX.length);
-  const pathWithoutPrefix = urlPath.split('?')[0] ?? urlPath;
-  const parts = pathWithoutPrefix.split('/');
-
-  // Need at least plugin name and one path segment
-  if (parts.length < 2 || !parts[0] || !parts[1]) {
+export function getPluginFromWebhookUrl(url: string): string | null {
+  const match = url.match(WEBHOOK_PATTERN);
+  if (!match) {
     return null;
   }
-
-  return {
-    pluginName: parts[0],
-    webhookPath: parts.slice(1).join('/'),
-  };
+  return match[1] || null;
 }
 
 /**
@@ -114,18 +102,21 @@ export async function webhookHandler(
     return;
   }
 
-  // Parse the URL to get plugin name and path
-  const parsed = parseWebhookUrl(req.url || '');
-  if (!parsed) {
+  // Extract plugin name from URL
+  const pluginName = getPluginFromWebhookUrl(req.url || '');
+  if (!pluginName) {
     res.writeHead(404, { 'Content-Type': 'application/json' });
-    res.end(JSON.stringify({ error: 'Invalid webhook URL format' }));
+    res.end(
+      JSON.stringify({
+        error:
+          'Invalid webhook URL format. Expected: /_webhooks/{plugin-name}/sync',
+      })
+    );
     return;
   }
 
-  const { pluginName, webhookPath } = parsed;
-
   // Look up the registered handler
-  const handler = defaultWebhookRegistry.getHandler(pluginName, webhookPath);
+  const handler = defaultWebhookRegistry.getHandler(pluginName);
   if (!handler) {
     res.writeHead(404, { 'Content-Type': 'application/json' });
     res.end(JSON.stringify({ error: 'Webhook handler not found' }));
@@ -147,23 +138,17 @@ export async function webhookHandler(
     return;
   }
 
-  // Verify signature if handler requires it
+  // Verify signature if handler has verification configured
   if (handler.verifySignature) {
     try {
       const isValid = await handler.verifySignature(req, rawBody);
       if (!isValid) {
-        console.warn(
-          `Webhook signature verification failed: ${pluginName}/${webhookPath}`
-        );
         res.writeHead(401, { 'Content-Type': 'application/json' });
         res.end(JSON.stringify({ error: 'Invalid signature' }));
         return;
       }
     } catch (error) {
-      console.error(
-        `Webhook signature verification error: ${pluginName}/${webhookPath}`,
-        error
-      );
+      console.error('Signature verification error:', error);
       res.writeHead(401, { 'Content-Type': 'application/json' });
       res.end(JSON.stringify({ error: 'Signature verification failed' }));
       return;
@@ -183,12 +168,11 @@ export async function webhookHandler(
     }
   }
 
-  console.log(`Webhook received: ${pluginName}/${webhookPath}`);
+  console.log(`Webhook received: ${pluginName}/sync`);
 
   // Create the queued webhook object
   let queuedWebhook: QueuedWebhook = {
     pluginName,
-    path: webhookPath,
     rawBody,
     body,
     headers: req.headers as Record<string, string | string[] | undefined>,
diff --git a/packages/core/tests/integration/webhook-routing.test.ts b/packages/core/tests/integration/webhook-routing.test.ts
index b52f440..17eb1b8 100644
--- a/packages/core/tests/integration/webhook-routing.test.ts
+++ b/packages/core/tests/integration/webhook-routing.test.ts
@@ -140,7 +140,7 @@ describe('webhook routing integration', () => {
 
   describe('webhook endpoint routing', () => {
     it('should return 404 for unregistered webhook', async () => {
-      const response = await makeRequest(server, '/_webhooks/unknown/path', {
+      const response = await makeRequest(server, '/_webhooks/unknown/sync', {
         body: '{}',
       });
 
@@ -149,12 +149,11 @@ describe('webhook routing integration', () => {
       expect(body.error).toBe('Webhook handler not found');
     });
 
-    it('should route to correct handler based on plugin and path', async () => {
+    it('should route to correct handler based on plugin', async () => {
       let handlerCalled = false;
       let receivedBody: unknown;
 
       const webhook: WebhookRegistration = {
-        path: 'entry-update',
         handler: async (_req, res, context) => {
           handlerCalled = true;
           receivedBody = context.body;
@@ -166,13 +165,9 @@ describe('webhook routing integration', () => {
       registry.register('contentful', webhook);
 
       const payload = { type: 'entry.publish', entryId: '123' };
-      const response = await makeRequest(
-        server,
-        '/_webhooks/contentful/entry-update',
-        {
-          body: JSON.stringify(payload),
-        }
-      );
+      const response = await makeRequest(server, '/_webhooks/contentful/sync', {
+        body: JSON.stringify(payload),
+      });
 
       // Webhook is queued with 202 response
       expect(response.statusCode).toBe(202);
@@ -186,14 +181,13 @@ describe('webhook routing integration', () => {
 
     it('should include CORS headers in webhook responses', async () => {
       registry.register('plugin', {
-        path: 'test',
         handler: async (_req, res) => {
           res.writeHead(200);
           res.end('OK');
         },
       });
 
-      const response = await makeRequest(server, '/_webhooks/plugin/test', {
+      const response = await makeRequest(server, '/_webhooks/plugin/sync', {
         body: '{}',
       });
 
@@ -205,14 +199,13 @@ describe('webhook routing integration', () => {
 
     it('should return 405 for GET requests to webhook endpoints', async () => {
       registry.register('plugin', {
-        path: 'test',
         handler: async (_req, res) => {
           res.writeHead(200);
           res.end('OK');
         },
       });
 
-      const response = await makeRequest(server, '/_webhooks/plugin/test', {
+      const response = await makeRequest(server, '/_webhooks/plugin/sync', {
         method: 'GET',
       });
 
@@ -225,7 +218,6 @@ describe('webhook routing integration', () => {
       let receivedContext: WebhookHandlerContext | undefined;
 
       registry.register('test-plugin', {
-        path: 'sync',
         handler: async (_req, res, context) => {
           receivedContext = context;
           res.writeHead(200);
@@ -252,7 +244,6 @@ describe('webhook routing integration', () => {
       let receivedRawBody: Buffer | undefined;
 
       registry.register('plugin', {
-        path: 'test',
         handler: async (_req, res, context) => {
           receivedRawBody = context.rawBody;
           res.writeHead(200);
@@ -261,7 +252,7 @@ describe('webhook routing integration', () => {
       });
 
       const payload = { test: 'data' };
-      await makeRequest(server, '/_webhooks/plugin/test', {
+      await makeRequest(server, '/_webhooks/plugin/sync', {
         body: JSON.stringify(payload),
       });
 
@@ -276,7 +267,6 @@ describe('webhook routing integration', () => {
   describe('node creation from webhook', () => {
     it('should allow creating nodes via webhook handler', async () => {
       registry.register('cms-plugin', {
-        path: 'content-update',
         handler: async (_req, res, context) => {
           const { body, actions } = context;
           const payload = body as { contentId: string; title: string };
@@ -296,13 +286,9 @@ describe('webhook routing integration', () => {
       });
 
       const payload = { contentId: 'entry-123', title: 'Test Entry' };
-      const response = await makeRequest(
-        server,
-        '/_webhooks/cms-plugin/content-update',
-        {
-          body: JSON.stringify(payload),
-        }
-      );
+      const response = await makeRequest(server, '/_webhooks/cms-plugin/sync', {
+        body: JSON.stringify(payload),
+      });
 
       // Webhook is queued
       expect(response.statusCode).toBe(202);
@@ -335,7 +321,6 @@ describe('webhook routing integration', () => {
       });
 
       registry.register('plugin', {
-        path: 'delete',
         handler: async (_req, res, context) => {
           const { body, actions } = context;
           const payload = body as { nodeId: string };
@@ -347,7 +332,7 @@ describe('webhook routing integration', () => {
         },
       });
 
-      await makeRequest(server, '/_webhooks/plugin/delete', {
+      await makeRequest(server, '/_webhooks/plugin/sync', {
         body: JSON.stringify({ nodeId: 'node-to-delete' }),
       });
 
@@ -362,7 +347,6 @@ describe('webhook routing integration', () => {
   describe('signature verification', () => {
     it('should return 401 when signature verification fails', async () => {
       registry.register('secure-plugin', {
-        path: 'secure-hook',
         handler: async (_req, res) => {
           res.writeHead(200);
           res.end('OK');
@@ -374,7 +358,7 @@ describe('webhook routing integration', () => {
 
       const response = await makeRequest(
         server,
-        '/_webhooks/secure-plugin/secure-hook',
+        '/_webhooks/secure-plugin/sync',
         {
           body: '{}',
         }
@@ -389,7 +373,6 @@ describe('webhook routing integration', () => {
       let handlerCalled = false;
 
       registry.register('secure-plugin', {
-        path: 'secure-hook',
         handler: async (_req, res) => {
           handlerCalled = true;
           res.writeHead(200);
@@ -403,7 +386,7 @@ describe('webhook routing integration', () => {
 
       const response = await makeRequest(
         server,
-        '/_webhooks/secure-plugin/secure-hook',
+        '/_webhooks/secure-plugin/sync',
         {
           body: '{}',
           headers: {
@@ -425,14 +408,13 @@ describe('webhook routing integration', () => {
   describe('error handling', () => {
     it('should return 400 for invalid JSON body', async () => {
       registry.register('plugin', {
-        path: 'test',
         handler: async (_req, res) => {
           res.writeHead(200);
           res.end('OK');
         },
       });
 
-      const response = await makeRequest(server, '/_webhooks/plugin/test', {
+      const response = await makeRequest(server, '/_webhooks/plugin/sync', {
         body: 'not valid json {{{',
         headers: {
           'Content-Type': 'application/json',
@@ -446,13 +428,12 @@ describe('webhook routing integration', () => {
 
     it('should queue webhook even if handler will throw (error happens during batch processing)', async () => {
       registry.register('plugin', {
-        path: 'error',
         handler: async () => {
           throw new Error('Something went wrong');
         },
       });
 
-      const response = await makeRequest(server, '/_webhooks/plugin/error', {
+      const response = await makeRequest(server, '/_webhooks/plugin/sync', {
         body: '{}',
       });
 
@@ -471,7 +452,6 @@ describe('webhook routing integration', () => {
       const calls: string[] = [];
 
       registry.register('plugin-a', {
-        path: 'update',
         handler: async (_req, res) => {
           calls.push('plugin-a');
           res.writeHead(200);
@@ -480,7 +460,6 @@ describe('webhook routing integration', () => {
       });
 
       registry.register('plugin-b', {
-        path: 'update',
         handler: async (_req, res) => {
           calls.push('plugin-b');
           res.writeHead(200);
@@ -489,12 +468,12 @@ describe('webhook routing integration', () => {
       });
 
       // Call plugin-a
-      await makeRequest(server, '/_webhooks/plugin-a/update', { body: '{}' });
+      await makeRequest(server, '/_webhooks/plugin-a/sync', { body: '{}' });
       await queue.flush();
       expect(calls).toEqual(['plugin-a']);
 
       // Call plugin-b
-      await makeRequest(server, '/_webhooks/plugin-b/update', { body: '{}' });
+      await makeRequest(server, '/_webhooks/plugin-b/sync', { body: '{}' });
       await queue.flush();
       expect(calls).toEqual(['plugin-a', 'plugin-b']);
     });
@@ -581,7 +560,6 @@ describe('webhook routing integration', () => {
 
       // Register a simple handler
       registry.register('test-plugin', {
-        path: 'sync',
         handler: async (_req, res) => {
           res.writeHead(200);
           res.end('OK');
@@ -632,7 +610,6 @@ describe('webhook routing integration', () => {
 
       // Register handlers for multiple plugins
       registry.register('plugin-a', {
-        path: 'update',
         handler: async (_req, res) => {
           res.writeHead(200);
           res.end('OK');
@@ -640,7 +617,6 @@ describe('webhook routing integration', () => {
       });
 
       registry.register('plugin-b', {
-        path: 'sync',
         handler: async (_req, res) => {
           res.writeHead(200);
           res.end('OK');
@@ -651,9 +627,9 @@ describe('webhook routing integration', () => {
       receivedOutboundPayloads = [];
 
       // Send webhooks to different plugins
-      await makeRequest(server, '/_webhooks/plugin-a/update', { body: '{}' });
+      await makeRequest(server, '/_webhooks/plugin-a/sync', { body: '{}' });
       await makeRequest(server, '/_webhooks/plugin-b/sync', { body: '{}' });
-      await makeRequest(server, '/_webhooks/plugin-a/update', { body: '{}' });
+      await makeRequest(server, '/_webhooks/plugin-a/sync', { body: '{}' });
 
       await outboundQueue.flush();
       await new Promise((resolve) => setTimeout(resolve, 100));
@@ -715,7 +691,6 @@ describe('webhook routing integration', () => {
         outboundQueue.on('webhook:batch-complete', batchCompleteHandler);
 
         registry.register('plugin', {
-          path: 'test',
           handler: async (_req, res) => {
             res.writeHead(200);
             res.end('OK');
@@ -725,7 +700,7 @@ describe('webhook routing integration', () => {
         // Clear payloads right before sending webhooks (in case of delayed arrivals from previous tests)
         receivedOutboundPayloads = [];
 
-        await makeRequest(server, '/_webhooks/plugin/test', { body: '{}' });
+        await makeRequest(server, '/_webhooks/plugin/sync', { body: '{}' });
         await outboundQueue.flush();
         await new Promise((resolve) => setTimeout(resolve, 100));
 
diff --git a/packages/core/tests/unit/handlers/webhook.test.ts b/packages/core/tests/unit/handlers/webhook.test.ts
index 209c00e..c84672c 100644
--- a/packages/core/tests/unit/handlers/webhook.test.ts
+++ b/packages/core/tests/unit/handlers/webhook.test.ts
@@ -3,7 +3,7 @@ import { EventEmitter } from 'node:events';
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import {
   isWebhookRequest,
-  parseWebhookUrl,
+  getPluginFromWebhookUrl,
   webhookHandler,
   WEBHOOK_PATH_PREFIX,
 } from '@/handlers/webhook.js';
@@ -80,33 +80,20 @@ function emitBody(
   });
 }
 
-// Sample webhook handler for testing
-function createTestWebhook(
-  path: string,
-  options: {
-    handler?: WebhookRegistration['handler'];
-    verifySignature?: WebhookRegistration['verifySignature'];
-  } = {}
-): WebhookRegistration {
-  const webhook: WebhookRegistration = {
-    path,
-    handler:
-      options.handler ||
-      (async (_req, res, _context) => {
-        res.writeHead(200, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({ received: true }));
-      }),
+// Sample webhook handler for testing (simplified - no path)
+function createTestWebhook(): WebhookRegistration {
+  return {
+    handler: async (_req, res, _context) => {
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ received: true }));
+    },
   };
-  if (options.verifySignature) {
-    webhook.verifySignature = options.verifySignature;
-  }
-  return webhook;
 }
 
 describe('isWebhookRequest', () => {
   it('should return true for valid webhook URLs', () => {
-    expect(isWebhookRequest('/_webhooks/plugin/path')).toBe(true);
-    expect(isWebhookRequest('/_webhooks/contentful/entry-update')).toBe(true);
+    expect(isWebhookRequest('/_webhooks/plugin/sync')).toBe(true);
+    expect(isWebhookRequest('/_webhooks/contentful/sync')).toBe(true);
     expect(isWebhookRequest('/_webhooks/my-plugin/sync')).toBe(true);
   });
 
@@ -114,8 +101,8 @@ describe('isWebhookRequest', () => {
     expect(isWebhookRequest('/graphql')).toBe(false);
     expect(isWebhookRequest('/health')).toBe(false);
     expect(isWebhookRequest('/ready')).toBe(false);
-    expect(isWebhookRequest('/webhooks/plugin/path')).toBe(false);
-    expect(isWebhookRequest('/_webhook/plugin/path')).toBe(false);
+    expect(isWebhookRequest('/webhooks/plugin/sync')).toBe(false);
+    expect(isWebhookRequest('/_webhook/plugin/sync')).toBe(false);
     expect(isWebhookRequest('/')).toBe(false);
   });
 
@@ -126,43 +113,29 @@ describe('isWebhookRequest', () => {
   });
 });
 
-describe('parseWebhookUrl', () => {
-  it('should parse valid webhook URLs', () => {
-    expect(parseWebhookUrl('/_webhooks/plugin/path')).toEqual({
-      pluginName: 'plugin',
-      webhookPath: 'path',
-    });
-
-    expect(parseWebhookUrl('/_webhooks/contentful/entry-update')).toEqual({
-      pluginName: 'contentful',
-      webhookPath: 'entry-update',
-    });
-
-    expect(parseWebhookUrl('/_webhooks/my-plugin/sync')).toEqual({
-      pluginName: 'my-plugin',
-      webhookPath: 'sync',
-    });
-  });
-
-  it('should handle multi-segment paths', () => {
-    expect(parseWebhookUrl('/_webhooks/plugin/path/subpath')).toEqual({
-      pluginName: 'plugin',
-      webhookPath: 'path/subpath',
-    });
+describe('getPluginFromWebhookUrl', () => {
+  it('should extract plugin name from valid webhook URLs', () => {
+    expect(getPluginFromWebhookUrl('/_webhooks/plugin/sync')).toBe('plugin');
+    expect(getPluginFromWebhookUrl('/_webhooks/contentful/sync')).toBe(
+      'contentful'
+    );
+    expect(getPluginFromWebhookUrl('/_webhooks/my-plugin/sync')).toBe(
+      'my-plugin'
+    );
   });
 
   it('should handle query strings', () => {
-    expect(parseWebhookUrl('/_webhooks/plugin/path?foo=bar')).toEqual({
-      pluginName: 'plugin',
-      webhookPath: 'path',
-    });
+    expect(getPluginFromWebhookUrl('/_webhooks/plugin/sync?foo=bar')).toBe(
+      'plugin'
+    );
   });
 
   it('should return null for invalid URLs', () => {
-    expect(parseWebhookUrl('/graphql')).toBeNull();
-    expect(parseWebhookUrl('/_webhooks/')).toBeNull();
-    expect(parseWebhookUrl('/_webhooks/plugin')).toBeNull();
-    expect(parseWebhookUrl('/_webhooks/plugin/')).toBeNull();
+    expect(getPluginFromWebhookUrl('/graphql')).toBeNull();
+    expect(getPluginFromWebhookUrl('/_webhooks/')).toBeNull();
+    expect(getPluginFromWebhookUrl('/_webhooks/plugin')).toBeNull();
+    expect(getPluginFromWebhookUrl('/_webhooks/plugin/')).toBeNull();
+    expect(getPluginFromWebhookUrl('/_webhooks/plugin/other-path')).toBeNull();
   });
 });
 
@@ -186,7 +159,7 @@ describe('webhookHandler', () => {
 
   describe('HTTP method validation', () => {
     it('should return 405 for GET requests', async () => {
-      const req = createMockRequest('GET', '/_webhooks/plugin/path');
+      const req = createMockRequest('GET', '/_webhooks/plugin/sync');
       const res = createMockResponse();
 
       await webhookHandler(req, res);
@@ -197,7 +170,7 @@ describe('webhookHandler', () => {
     });
 
     it('should return 405 for PUT requests', async () => {
-      const req = createMockRequest('PUT', '/_webhooks/plugin/path');
+      const req = createMockRequest('PUT', '/_webhooks/plugin/sync');
       const res = createMockResponse();
 
       await webhookHandler(req, res);
@@ -206,7 +179,7 @@ describe('webhookHandler', () => {
     });
 
     it('should return 405 for DELETE requests', async () => {
-      const req = createMockRequest('DELETE', '/_webhooks/plugin/path');
+      const req = createMockRequest('DELETE', '/_webhooks/plugin/sync');
       const res = createMockResponse();
 
       await webhookHandler(req, res);
@@ -225,11 +198,11 @@ describe('webhookHandler', () => {
 
       expect(res._statusCode).toBe(404);
       const body = JSON.parse(res._body);
-      expect(body.error).toBe('Invalid webhook URL format');
+      expect(body.error).toContain('Invalid webhook URL format');
     });
 
-    it('should return 404 when no handler is registered', async () => {
-      const req = createMockRequest('POST', '/_webhooks/unknown-plugin/path');
+    it('should return 404 for missing /sync path', async () => {
+      const req = createMockRequest('POST', '/_webhooks/plugin');
       const res = createMockResponse();
 
       emitBody(req, '{}');
@@ -237,25 +210,13 @@ describe('webhookHandler', () => {
 
       expect(res._statusCode).toBe(404);
       const body = JSON.parse(res._body);
-      expect(body.error).toBe('Webhook handler not found');
-    });
-
-    it('should return 404 for wrong plugin name', async () => {
-      registry.register('plugin-a', createTestWebhook('path'));
-
-      const req = createMockRequest('POST', '/_webhooks/plugin-b/path');
-      const res = createMockResponse();
-
-      emitBody(req, '{}');
-      await webhookHandler(req, res);
-
-      expect(res._statusCode).toBe(404);
+      expect(body.error).toContain('Invalid webhook URL format');
     });
 
     it('should return 404 for wrong path', async () => {
-      registry.register('plugin', createTestWebhook('path-a'));
+      registry.register('plugin', createTestWebhook());
 
-      const req = createMockRequest('POST', '/_webhooks/plugin/path-b');
+      const req = createMockRequest('POST', '/_webhooks/plugin/other-path');
       const res = createMockResponse();
 
       emitBody(req, '{}');
@@ -263,141 +224,37 @@ describe('webhookHandler', () => {
 
       expect(res._statusCode).toBe(404);
     });
-  });
-
-  describe('signature verification', () => {
-    it('should return 401 when verifySignature returns false', async () => {
-      const consoleWarnSpy = vi
-        .spyOn(console, 'warn')
-        .mockImplementation(() => {});
-
-      registry.register(
-        'plugin',
-        createTestWebhook('path', {
-          verifySignature: () => false,
-        })
-      );
-
-      const req = createMockRequest('POST', '/_webhooks/plugin/path');
-      const res = createMockResponse();
-
-      emitBody(req, '{}');
-      await webhookHandler(req, res);
-
-      expect(res._statusCode).toBe(401);
-      const body = JSON.parse(res._body);
-      expect(body.error).toBe('Invalid signature');
-      expect(consoleWarnSpy).toHaveBeenCalled();
-
-      consoleWarnSpy.mockRestore();
-    });
 
-    it('should return 401 when verifySignature throws', async () => {
-      const consoleErrorSpy = vi
-        .spyOn(console, 'error')
-        .mockImplementation(() => {});
-
-      registry.register(
-        'plugin',
-        createTestWebhook('path', {
-          verifySignature: () => {
-            throw new Error('Signature error');
-          },
-        })
-      );
-
-      const req = createMockRequest('POST', '/_webhooks/plugin/path');
+    it('should return 404 when no handler is registered', async () => {
+      const req = createMockRequest('POST', '/_webhooks/unknown-plugin/sync');
       const res = createMockResponse();
 
       emitBody(req, '{}');
       await webhookHandler(req, res);
 
-      expect(res._statusCode).toBe(401);
+      expect(res._statusCode).toBe(404);
       const body = JSON.parse(res._body);
-      expect(body.error).toBe('Signature verification failed');
-
-      consoleErrorSpy.mockRestore();
-    });
-
-    it('should queue webhook when verifySignature returns true', async () => {
-      const consoleLogSpy = vi
-        .spyOn(console, 'log')
-        .mockImplementation(() => {});
-
-      registry.register(
-        'plugin',
-        createTestWebhook('path', {
-          verifySignature: () => true,
-        })
-      );
-
-      const req = createMockRequest('POST', '/_webhooks/plugin/path');
-      const res = createMockResponse();
-
-      emitBody(req, '{}');
-      await webhookHandler(req, res);
-
-      // Webhook is queued, not immediately processed
-      expect(res._statusCode).toBe(202);
-      expect(queue.size()).toBe(1);
-
-      consoleLogSpy.mockRestore();
-    });
-
-    it('should support async verifySignature', async () => {
-      const consoleLogSpy = vi
-        .spyOn(console, 'log')
-        .mockImplementation(() => {});
-
-      registry.register(
-        'plugin',
-        createTestWebhook('path', {
-          verifySignature: async () => {
-            await new Promise((resolve) => setTimeout(resolve, 10));
-            return true;
-          },
-        })
-      );
-
-      const req = createMockRequest('POST', '/_webhooks/plugin/path');
-      const res = createMockResponse();
-
-      emitBody(req, '{}');
-      await webhookHandler(req, res);
-
-      // Webhook is queued after signature verification
-      expect(res._statusCode).toBe(202);
-      expect(queue.size()).toBe(1);
-
-      consoleLogSpy.mockRestore();
+      expect(body.error).toBe('Webhook handler not found');
     });
 
-    it('should skip verification if no verifySignature defined', async () => {
-      const consoleLogSpy = vi
-        .spyOn(console, 'log')
-        .mockImplementation(() => {});
-
-      registry.register('plugin', createTestWebhook('path'));
+    it('should return 404 for wrong plugin name', async () => {
+      registry.register('plugin-a', createTestWebhook());
 
-      const req = createMockRequest('POST', '/_webhooks/plugin/path');
+      const req = createMockRequest('POST', '/_webhooks/plugin-b/sync');
       const res = createMockResponse();
 
       emitBody(req, '{}');
       await webhookHandler(req, res);
 
-      // Webhook is queued without signature verification
-      expect(res._statusCode).toBe(202);
-      expect(queue.size()).toBe(1);
-
-      consoleLogSpy.mockRestore();
+      expect(res._statusCode).toBe(404);
     });
   });
 
   describe('JSON body parsing', () => {
     it('should return 400 for invalid JSON with application/json content-type', async () => {
-      registry.register('plugin', createTestWebhook('path'));
+      registry.register('plugin', createTestWebhook());
 
-      const req = createMockRequest('POST', '/_webhooks/plugin/path', {
+      const req = createMockRequest('POST', '/_webhooks/plugin/sync', {
         'content-type': 'application/json',
       });
       const res = createMockResponse();
@@ -423,9 +280,9 @@ describe('webhookHandler', () => {
         originalEnqueue(webhook);
       };
 
-      registry.register('plugin', createTestWebhook('path'));
+      registry.register('plugin', createTestWebhook());
 
-      const req = createMockRequest('POST', '/_webhooks/plugin/path', {
+      const req = createMockRequest('POST', '/_webhooks/plugin/sync', {
         'content-type': 'application/json',
       });
       const res = createMockResponse();
@@ -453,9 +310,9 @@ describe('webhookHandler', () => {
         originalEnqueue(webhook);
       };
 
-      registry.register('plugin', createTestWebhook('path'));
+      registry.register('plugin', createTestWebhook());
 
-      const req = createMockRequest('POST', '/_webhooks/plugin/path', {
+      const req = createMockRequest('POST', '/_webhooks/plugin/sync', {
         'content-type': 'text/plain',
       });
       const res = createMockResponse();
@@ -482,9 +339,9 @@ describe('webhookHandler', () => {
         originalEnqueue(webhook);
       };
 
-      registry.register('plugin', createTestWebhook('path'));
+      registry.register('plugin', createTestWebhook());
 
-      const req = createMockRequest('POST', '/_webhooks/plugin/path');
+      const req = createMockRequest('POST', '/_webhooks/plugin/sync');
       const res = createMockResponse();
 
       const bodyText = 'raw body content';
@@ -513,9 +370,9 @@ describe('webhookHandler', () => {
         originalEnqueue(webhook);
       };
 
-      registry.register('test-plugin', createTestWebhook('update'));
+      registry.register('test-plugin', createTestWebhook());
 
-      const req = createMockRequest('POST', '/_webhooks/test-plugin/update', {
+      const req = createMockRequest('POST', '/_webhooks/test-plugin/sync', {
         'content-type': 'application/json',
       });
       const res = createMockResponse();
@@ -526,7 +383,6 @@ describe('webhookHandler', () => {
       expect(res._statusCode).toBe(202);
       expect(queuedWebhook).toBeDefined();
       expect(queuedWebhook?.pluginName).toBe('test-plugin');
-      expect(queuedWebhook?.path).toBe('update');
       expect(queuedWebhook?.body).toEqual({ test: true });
       expect(queuedWebhook?.rawBody).toBeInstanceOf(Buffer);
       expect(queuedWebhook?.timestamp).toBeGreaterThan(0);
@@ -539,9 +395,9 @@ describe('webhookHandler', () => {
         .spyOn(console, 'log')
         .mockImplementation(() => {});
 
-      registry.register('plugin', createTestWebhook('path'));
+      registry.register('plugin', createTestWebhook());
 
-      const req = createMockRequest('POST', '/_webhooks/plugin/path');
+      const req = createMockRequest('POST', '/_webhooks/plugin/sync');
       const res = createMockResponse();
 
       emitBody(req, '{}');
@@ -559,16 +415,16 @@ describe('webhookHandler', () => {
         .spyOn(console, 'log')
         .mockImplementation(() => {});
 
-      registry.register('my-plugin', createTestWebhook('my-path'));
+      registry.register('my-plugin', createTestWebhook());
 
-      const req = createMockRequest('POST', '/_webhooks/my-plugin/my-path');
+      const req = createMockRequest('POST', '/_webhooks/my-plugin/sync');
       const res = createMockResponse();
 
       emitBody(req, '{}');
       await webhookHandler(req, res);
 
       expect(consoleLogSpy).toHaveBeenCalledWith(
-        'Webhook received: my-plugin/my-path'
+        'Webhook received: my-plugin/sync'
       );
 
       consoleLogSpy.mockRestore();
@@ -587,9 +443,9 @@ describe('webhookHandler', () => {
         originalEnqueue(webhook);
       };
 
-      registry.register('plugin', createTestWebhook('path'));
+      registry.register('plugin', createTestWebhook());
 
-      const req = createMockRequest('POST', '/_webhooks/plugin/path', {
+      const req = createMockRequest('POST', '/_webhooks/plugin/sync', {
         'content-type': 'application/json',
         'x-custom-header': 'custom-value',
       });
@@ -620,9 +476,9 @@ describe('webhookHandler', () => {
         },
       });
 
-      registry.register('plugin', createTestWebhook('path'));
+      registry.register('plugin', createTestWebhook());
 
-      const req = createMockRequest('POST', '/_webhooks/plugin/path');
+      const req = createMockRequest('POST', '/_webhooks/plugin/sync');
       const res = createMockResponse();
 
       emitBody(req, '{}');
@@ -643,9 +499,9 @@ describe('webhookHandler', () => {
         onWebhookReceived: async () => null,
       });
 
-      registry.register('plugin', createTestWebhook('path'));
+      registry.register('plugin', createTestWebhook());
 
-      const req = createMockRequest('POST', '/_webhooks/plugin/path');
+      const req = createMockRequest('POST', '/_webhooks/plugin/sync');
       const res = createMockResponse();
 
       emitBody(req, '{}');
@@ -679,9 +535,9 @@ describe('webhookHandler', () => {
         }),
       });
 
-      registry.register('plugin', createTestWebhook('path'));
+      registry.register('plugin', createTestWebhook());
 
-      const req = createMockRequest('POST', '/_webhooks/plugin/path', {
+      const req = createMockRequest('POST', '/_webhooks/plugin/sync', {
         'content-type': 'application/json',
       });
       const res = createMockResponse();
@@ -720,9 +576,9 @@ describe('webhookHandler', () => {
         },
       });
 
-      registry.register('plugin', createTestWebhook('path'));
+      registry.register('plugin', createTestWebhook());
 
-      const req = createMockRequest('POST', '/_webhooks/plugin/path', {
+      const req = createMockRequest('POST', '/_webhooks/plugin/sync', {
         'content-type': 'application/json',
       });
       const res = createMockResponse();
@@ -742,9 +598,9 @@ describe('webhookHandler', () => {
 
   describe('body size limit', () => {
     it('should return 413 for oversized body', async () => {
-      registry.register('plugin', createTestWebhook('path'));
+      registry.register('plugin', createTestWebhook());
 
-      const req = createMockRequest('POST', '/_webhooks/plugin/path');
+      const req = createMockRequest('POST', '/_webhooks/plugin/sync');
       const res = createMockResponse();
 
       // Add destroy method to mock request

From c2cc2b48bba6f14f2f68b93eb542f9d3fc25b1f3 Mon Sep 17 00:00:00 2001
From: dawidurbanski <hi@dawidurbanski.com>
Date: Tue, 23 Dec 2025 01:31:03 +0100
Subject: [PATCH 28/46] feat(core): add default webhook handler with CRUD
 operations

Provide a built-in webhook handler that processes standardized payloads
for node CRUD operations, automatically registered for plugins.

- DefaultWebhookPayload with create/update/delete/upsert operations
- createDefaultWebhookHandler factory with idField support
- registerDefaultWebhook for auto-registration during plugin loading
- registerPluginWebhookHandler for custom plugin handlers
- Integration with webhook processor for batch execution
---
 .changeset/default-webhook-handler.md         |  24 +-
 packages/core/src/loader.ts                   |  95 ++++---
 packages/core/src/webhooks/processor.ts       |  15 +-
 .../core/src/webhooks/register-default.ts     | 128 ++++-----
 .../remote-udl-webhooks/udl.config.ts         |   8 +-
 .../unit/webhooks/register-default.test.ts    | 262 ++++++++----------
 6 files changed, 232 insertions(+), 300 deletions(-)

diff --git a/.changeset/default-webhook-handler.md b/.changeset/default-webhook-handler.md
index bb2e4e9..d698f05 100644
--- a/.changeset/default-webhook-handler.md
+++ b/.changeset/default-webhook-handler.md
@@ -4,30 +4,22 @@
 
 Add default webhook handler for standardized CRUD operations
 
-This release introduces a default webhook handler that provides a standardized way to create, update, and delete nodes via webhooks. This eliminates the need for plugins to implement their own webhook handlers for basic CRUD operations.
+This release introduces a default webhook handler that provides a standardized way to create, update, and delete nodes via webhooks. Every loaded plugin automatically gets a webhook endpoint registered with zero configuration required.
 
 **Features:**
 
-- Automatic registration of `/sync` webhook endpoint for each loaded plugin
+- Automatic registration of `/_webhooks/{plugin-name}/sync` endpoint for every plugin
 - Standardized payload format for `create`, `update`, `delete`, and `upsert` operations
 - Support for custom `idField` to look up nodes by external identifiers
-- Configurable per-plugin path overrides or disabling
-- Integration with plugin loading for automatic setup
+- Won't overwrite custom handlers if plugin registers its own
 
-**Configuration:**
+**Zero Configuration:**
 
 ```typescript
+// No config needed - default webhooks just work
+// Every plugin gets: /_webhooks/{plugin-name}/sync
 export const { config } = defineConfig({
-  defaultWebhook: {
-    enabled: true,
-    path: 'sync', // Default endpoint path
-    plugins: {
-      // Customize path for specific plugin
-      contentful: { path: 'content-sync' },
-      // Disable for a specific plugin
-      'legacy-plugin': false,
-    },
-  },
+  plugins: ['@universal-data-layer/plugin-source-contentful'],
 });
 ```
 
@@ -65,7 +57,7 @@ curl -X POST http://localhost:4000/_webhooks/my-plugin/sync \
 
 **idField support:**
 
-When a plugin specifies an `idField` in its config, the default webhook handler can look up existing nodes by that field:
+When a plugin specifies an `idField` in its config, the default webhook handler looks up existing nodes by that field:
 
 ```typescript
 // Plugin config
diff --git a/packages/core/src/loader.ts b/packages/core/src/loader.ts
index f2ee888..aa95b4a 100644
--- a/packages/core/src/loader.ts
+++ b/packages/core/src/loader.ts
@@ -16,10 +16,10 @@ import type {
 import {
   defaultWebhookRegistry,
   registerDefaultWebhook,
+  registerPluginWebhookHandler,
   type WebhookRegistry,
-  type WebhookRegistration,
   type WebhookHooksConfig,
-  type DefaultWebhookHandlerConfig,
+  type PluginWebhookHandler,
 } from '@/webhooks/index.js';
 import type { ServerOptions as WebSocketServerOptions } from 'ws';
 
@@ -88,12 +88,17 @@ export interface CodegenConfig {
 }
 
 /**
- * Configuration for an outbound webhook trigger.
+ * Configuration for an outbound webhook.
  * Outbound webhooks are sent after batch processing to notify external systems.
  */
 export interface OutboundWebhookTriggerConfig {
-  /** URL to POST to */
+  /** URL to send the webhook to */
   url: string;
+  /**
+   * HTTP method to use.
+   * @default 'POST'
+   */
+  method?: 'POST' | 'GET';
   /**
    * Events to trigger on. '*' = all events.
    * @default ['*']
@@ -138,22 +143,23 @@ export interface RemoteWebhooksConfig {
   hooks?: WebhookHooksConfig;
 
   /**
-   * Outbound webhook triggers to notify after batch processing.
+   * Outbound webhooks to notify after batch processing.
    * These webhooks are sent after a batch of incoming webhooks has been processed,
    * enabling the "30 webhooks → 1 build" optimization.
    *
    * @example
    * ```typescript
-   * trigger: [
+   * outbound: [
    *   {
    *     url: 'https://api.vercel.com/v1/integrations/deploy/...',
+   *     method: 'POST', // or 'GET' for simple ping
    *     headers: { 'Authorization': 'Bearer token' },
    *     retries: 3,
    *   }
    * ]
    * ```
    */
-  trigger?: OutboundWebhookTriggerConfig[];
+  outbound?: OutboundWebhookTriggerConfig[];
 }
 
 /**
@@ -287,28 +293,6 @@ export interface UDLConfig {
    * Configuration for remote data synchronization (webhooks, etc.).
    */
   remote?: RemoteConfig;
-  /**
-   * Configuration for automatic default webhook handlers.
-   * When enabled, registers a default 'sync' webhook endpoint for each loaded plugin
-   * that accepts standardized create/update/delete/upsert payloads.
-   *
-   * @example
-   * ```typescript
-   * defineConfig({
-   *   defaultWebhook: {
-   *     enabled: true,
-   *     path: 'sync', // Default endpoint path for all plugins
-   *     plugins: {
-   *       // Customize path for specific plugin
-   *       'contentful': { path: 'content-sync' },
-   *       // Disable for a specific plugin
-   *       'legacy-plugin': false,
-   *     },
-   *   },
-   * });
-   * ```
-   */
-  defaultWebhook?: DefaultWebhookHandlerConfig;
 }
 
 /**
@@ -357,6 +341,33 @@ export interface UDLConfigFile {
   registerTypes?: <T = Record<string, unknown>>(
     context?: RegisterTypesContext<T>
   ) => void | Promise<void>;
+  /**
+   * Optional webhook handler export.
+   * When provided, replaces the default CRUD handler for this plugin's webhook endpoint.
+   * The handler receives all incoming webhooks at /_webhooks/{plugin-name}/sync.
+   *
+   * @example
+   * ```typescript
+   * export async function registerWebhookHandler({ req, res, actions, body }) {
+   *   // Verify signature
+   *   if (!verifySignature(req, body)) {
+   *     res.writeHead(401);
+   *     res.end('Invalid signature');
+   *     return;
+   *   }
+   *
+   *   // Handle the webhook
+   *   const eventType = req.headers['x-webhook-type'];
+   *   if (eventType === 'entry.publish') {
+   *     await actions.createNode(transformEntry(body), { ... });
+   *   }
+   *
+   *   res.writeHead(200);
+   *   res.end();
+   * }
+   * ```
+   */
+  registerWebhookHandler?: PluginWebhookHandler;
   /**
    * Optional reference resolver configuration.
    * Defines how references from this plugin are identified and resolved.
@@ -439,19 +450,11 @@ export async function loadConfigFile(
         store: options.store,
         owner: options.pluginName,
       });
-      const webhookRegistry = options.webhookRegistry ?? defaultWebhookRegistry;
-
-      // Create a bound registerWebhook function for this plugin
-      const registerWebhook = (webhook: WebhookRegistration): void => {
-        webhookRegistry.register(options.pluginName!, webhook);
-      };
-
       await module.sourceNodes({
         actions,
         createNodeId,
         createContentDigest,
         options: options.context?.options,
-        registerWebhook,
       });
     }
 
@@ -825,28 +828,28 @@ export async function loadPlugins(
             owner: actualPluginName,
           });
 
-          // Create a bound registerWebhook function for this plugin
-          const registerWebhook = (webhook: WebhookRegistration): void => {
-            webhookRegistry.register(actualPluginName, webhook);
-          };
-
           await module.sourceNodes({
             actions,
             createNodeId,
             createContentDigest,
             options: context?.options,
             cacheDir: cacheLocation,
-            registerWebhook,
           });
 
           registerPluginIndexes(nodeStore, actualPluginName, allIndexes);
 
-          // Register default webhook handler if enabled in config
-          if (appConfig?.defaultWebhook) {
+          // Register webhook handler for the plugin
+          // If plugin exports registerWebhookHandler, use it instead of default
+          if (module.registerWebhookHandler) {
+            registerPluginWebhookHandler(
+              webhookRegistry,
+              actualPluginName,
+              module.registerWebhookHandler
+            );
+          } else {
             registerDefaultWebhook(
               webhookRegistry,
               actualPluginName,
-              appConfig.defaultWebhook,
               pluginIdField
             );
           }
diff --git a/packages/core/src/webhooks/processor.ts b/packages/core/src/webhooks/processor.ts
index 3301f94..d25ae9e 100644
--- a/packages/core/src/webhooks/processor.ts
+++ b/packages/core/src/webhooks/processor.ts
@@ -17,6 +17,7 @@ import { getWebhookHooks } from './hooks.js';
 import { defaultStore } from '@/nodes/defaultStore.js';
 import { createNodeActions } from '@/nodes/actions/index.js';
 import type { WebhookHandlerContext } from './types.js';
+import { DEFAULT_WEBHOOK_PATH } from './default-handler.js';
 
 /**
  * Create a minimal mock IncomingMessage for queued webhook processing.
@@ -27,7 +28,7 @@ function createMockRequest(webhook: QueuedWebhook): IncomingMessage {
   const emitter = new EventEmitter();
   return Object.assign(emitter, {
     method: 'POST',
-    url: `/_webhooks/${webhook.pluginName}/${webhook.path}`,
+    url: `/_webhooks/${webhook.pluginName}/${DEFAULT_WEBHOOK_PATH}`,
     headers: webhook.headers,
     httpVersion: '1.1',
     httpVersionMajor: 1,
@@ -92,14 +93,11 @@ function createMockResponse(): ServerResponse {
  * @param webhook - The queued webhook to process
  */
 async function processWebhook(webhook: QueuedWebhook): Promise<void> {
-  const handler = defaultWebhookRegistry.getHandler(
-    webhook.pluginName,
-    webhook.path
-  );
+  const handler = defaultWebhookRegistry.getHandler(webhook.pluginName);
 
   if (!handler) {
     console.warn(
-      `⚠️ Handler not found for queued webhook: ${webhook.pluginName}/${webhook.path}`
+      `⚠️ Handler not found for queued webhook: ${webhook.pluginName}`
     );
     return;
   }
@@ -123,10 +121,7 @@ async function processWebhook(webhook: QueuedWebhook): Promise<void> {
   try {
     await handler.handler(mockReq, mockRes, context);
   } catch (error) {
-    console.error(
-      `❌ Error processing webhook ${webhook.pluginName}/${webhook.path}:`,
-      error
-    );
+    console.error(`❌ Error processing webhook ${webhook.pluginName}:`, error);
     // Don't rethrow - continue processing other webhooks in the batch
   }
 }
diff --git a/packages/core/src/webhooks/register-default.ts b/packages/core/src/webhooks/register-default.ts
index 5ce4cfa..2ccb89f 100644
--- a/packages/core/src/webhooks/register-default.ts
+++ b/packages/core/src/webhooks/register-default.ts
@@ -1,86 +1,54 @@
 /**
  * Default Webhook Registration Utility
  *
- * Provides functions to automatically register default webhook handlers
- * for plugins based on configuration.
+ * Automatically registers default webhook handlers for plugins.
+ * Convention-based: every plugin gets /_webhooks/{plugin-name}/sync
  */
 
 import type { WebhookRegistry } from './registry.js';
-import type { DefaultWebhookHandlerConfig } from './types.js';
+import type { PluginWebhookHandler, WebhookHandlerFn } from './types.js';
 import {
   createDefaultWebhookHandler,
   DEFAULT_WEBHOOK_PATH,
 } from './default-handler.js';
 
 /**
- * Register a default webhook handler for a plugin if enabled in configuration.
+ * Register a default webhook handler for a plugin.
  *
- * This function checks the `defaultWebhook` configuration and registers
- * a standardized webhook handler for the specified plugin. It respects:
- * - Global enable/disable setting
- * - Per-plugin enable/disable setting
- * - Custom paths (global and per-plugin)
- * - Existing custom handlers (won't overwrite)
- * - Plugin's idField for node lookups
+ * This function registers a standardized webhook handler at the
+ * convention-based path: /_webhooks/{plugin-name}/sync
+ *
+ * Features:
+ * - Zero configuration required
+ * - Won't overwrite existing custom handlers
+ * - Uses plugin's idField for node lookups if provided
  *
  * @param registry - The webhook registry to register with
  * @param pluginName - The plugin name to register for
- * @param config - The default webhook configuration
  * @param pluginIdField - The plugin's configured idField (from plugin's udl.config)
- * @returns The path that was registered, or null if not registered
+ * @returns true if registered, false if skipped (handler already exists)
  *
  * @example
  * ```typescript
- * const path = registerDefaultWebhook(registry, 'contentful', {
- *   enabled: true,
- *   path: 'sync',
- * }, 'contentfulId');
- * // path = 'sync' if registered, null if skipped
+ * registerDefaultWebhook(registry, 'contentful', 'contentfulId');
+ * // Registers: /_webhooks/contentful/sync
  * ```
  */
 export function registerDefaultWebhook(
   registry: WebhookRegistry,
   pluginName: string,
-  config: DefaultWebhookHandlerConfig | undefined,
   pluginIdField?: string
-): string | null {
-  // If config is not present, default handlers are disabled
-  if (!config) {
-    return null;
-  }
-
-  // Check if explicitly disabled globally
-  if (config.enabled === false) {
-    return null;
-  }
-
-  // Check per-plugin configuration
-  const pluginConfig = config.plugins?.[pluginName];
-
-  // If plugin is explicitly disabled
-  if (pluginConfig === false) {
-    console.log(`📭 Default webhook disabled for plugin: ${pluginName}`);
-    return null;
-  }
-
-  // Determine the path to use
-  const globalPath = config.path ?? DEFAULT_WEBHOOK_PATH;
-  const path =
-    typeof pluginConfig === 'object' && pluginConfig.path
-      ? pluginConfig.path
-      : globalPath;
-
-  // Check if handler already exists for this path (don't overwrite custom handlers)
-  if (registry.has(pluginName, path)) {
+): boolean {
+  // Check if handler already exists (don't overwrite custom handlers)
+  if (registry.has(pluginName)) {
     console.log(
-      `📌 Plugin ${pluginName} already has handler for '${path}', skipping default registration`
+      `📌 Plugin ${pluginName} already has handler, skipping default registration`
     );
-    return null;
+    return false;
   }
 
   // Register the default handler using the plugin's idField
   registry.register(pluginName, {
-    path,
     handler: createDefaultWebhookHandler(
       pluginName,
       pluginIdField ? { idField: pluginIdField } : {}
@@ -90,43 +58,53 @@ export function registerDefaultWebhook(
 
   const lookupInfo = pluginIdField ? ` (idField: ${pluginIdField})` : '';
   console.log(
-    `📬 Default webhook registered: /_webhooks/${pluginName}/${path}${lookupInfo}`
+    `📬 Default webhook registered: /_webhooks/${pluginName}/${DEFAULT_WEBHOOK_PATH}${lookupInfo}`
   );
-  return path;
+  return true;
 }
 
 /**
- * Register default webhooks for multiple plugins.
+ * Register a custom plugin webhook handler.
  *
- * Convenience function to register default handlers for all plugins
- * in a single call.
+ * Wraps the plugin's `registerWebhookHandler` export and registers it
+ * at the convention-based path: /_webhooks/{plugin-name}/sync
  *
  * @param registry - The webhook registry to register with
- * @param pluginNames - Array of plugin names to register
- * @param config - The default webhook configuration
- * @returns Map of plugin name to registered path (or null if not registered)
+ * @param pluginName - The plugin name to register for
+ * @param customHandler - The plugin's registerWebhookHandler export
+ * @returns true (always registers, replaces default)
  *
  * @example
  * ```typescript
- * const results = registerDefaultWebhooks(
- *   registry,
- *   ['contentful', 'shopify', 'custom-plugin'],
- *   { enabled: true }
- * );
- * // results: Map { 'contentful' => 'sync', 'shopify' => 'sync', ... }
+ * registerPluginWebhookHandler(registry, 'contentful', module.registerWebhookHandler);
+ * // Registers: /_webhooks/contentful/sync with custom handler
  * ```
  */
-export function registerDefaultWebhooks(
+export function registerPluginWebhookHandler(
   registry: WebhookRegistry,
-  pluginNames: string[],
-  config: DefaultWebhookHandlerConfig | undefined
-): Map<string, string | null> {
-  const results = new Map<string, string | null>();
+  pluginName: string,
+  customHandler: PluginWebhookHandler
+): boolean {
+  // Wrap the plugin's handler to match WebhookHandlerFn signature
+  const wrappedHandler: WebhookHandlerFn = async (req, res, context) => {
+    await customHandler({
+      req,
+      res,
+      actions: context.actions,
+      store: context.store,
+      body: context.body,
+      rawBody: context.rawBody,
+    });
+  };
 
-  for (const pluginName of pluginNames) {
-    const path = registerDefaultWebhook(registry, pluginName, config);
-    results.set(pluginName, path);
-  }
+  // Register the custom handler
+  registry.register(pluginName, {
+    handler: wrappedHandler,
+    description: `Custom webhook handler for ${pluginName}`,
+  });
 
-  return results;
+  console.log(
+    `📬 Custom webhook registered: /_webhooks/${pluginName}/${DEFAULT_WEBHOOK_PATH}`
+  );
+  return true;
 }
diff --git a/packages/core/tests/manual/features/remote-udl-webhooks/udl.config.ts b/packages/core/tests/manual/features/remote-udl-webhooks/udl.config.ts
index 3556615..859882d 100644
--- a/packages/core/tests/manual/features/remote-udl-webhooks/udl.config.ts
+++ b/packages/core/tests/manual/features/remote-udl-webhooks/udl.config.ts
@@ -17,10 +17,6 @@ export const config = defineConfig({
       options: {},
     },
   ],
-  // Enable default webhook handler for all plugins
-  // This allows the MSW handlers to send webhooks to update UDL nodes
-  defaultWebhook: {
-    enabled: true,
-    path: 'sync', // Endpoint: /_webhooks/remote-todo-source/sync
-  },
+  // Default webhook handler is now automatically registered for all plugins
+  // Endpoint: /_webhooks/remote-todo-source/sync
 });
diff --git a/packages/core/tests/unit/webhooks/register-default.test.ts b/packages/core/tests/unit/webhooks/register-default.test.ts
index 26aaf1f..b4e6e62 100644
--- a/packages/core/tests/unit/webhooks/register-default.test.ts
+++ b/packages/core/tests/unit/webhooks/register-default.test.ts
@@ -1,10 +1,18 @@
 import { describe, it, expect, beforeEach, vi } from 'vitest';
+import type { IncomingMessage, ServerResponse } from 'node:http';
 import { WebhookRegistry } from '@/webhooks/registry.js';
 import {
   registerDefaultWebhook,
-  registerDefaultWebhooks,
+  registerPluginWebhookHandler,
 } from '@/webhooks/register-default.js';
-import type { DefaultWebhookHandlerConfig } from '@/webhooks/types.js';
+import { DEFAULT_WEBHOOK_PATH } from '@/webhooks/default-handler.js';
+import type {
+  PluginWebhookHandler,
+  PluginWebhookHandlerContext,
+  WebhookHandlerContext,
+} from '@/webhooks/types.js';
+import type { NodeStore } from '@/nodes/store.js';
+import type { NodeActions } from '@/nodes/actions/index.js';
 
 describe('registerDefaultWebhook', () => {
   let registry: WebhookRegistry;
@@ -15,198 +23,158 @@ describe('registerDefaultWebhook', () => {
     consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
   });
 
-  it('should not register if config is undefined', () => {
-    const result = registerDefaultWebhook(registry, 'test-plugin', undefined);
+  it('should register with default path "sync"', () => {
+    const result = registerDefaultWebhook(registry, 'test-plugin');
 
-    expect(result).toBeNull();
-    expect(registry.size()).toBe(0);
-  });
-
-  it('should not register if enabled is false', () => {
-    const config: DefaultWebhookHandlerConfig = { enabled: false };
-    const result = registerDefaultWebhook(registry, 'test-plugin', config);
-
-    expect(result).toBeNull();
-    expect(registry.size()).toBe(0);
-  });
-
-  it('should register with default path "sync" when enabled', () => {
-    const config: DefaultWebhookHandlerConfig = { enabled: true };
-    const result = registerDefaultWebhook(registry, 'test-plugin', config);
-
-    expect(result).toBe('sync');
-    expect(registry.has('test-plugin', 'sync')).toBe(true);
-    expect(consoleSpy).toHaveBeenCalledWith(
-      '📬 Default webhook registered: /_webhooks/test-plugin/sync'
-    );
-  });
-
-  it('should register when config is empty object (enabled by default)', () => {
-    const config: DefaultWebhookHandlerConfig = {};
-    const result = registerDefaultWebhook(registry, 'test-plugin', config);
-
-    expect(result).toBe('sync');
-    expect(registry.has('test-plugin', 'sync')).toBe(true);
-  });
-
-  it('should use custom global path', () => {
-    const config: DefaultWebhookHandlerConfig = {
-      enabled: true,
-      path: 'custom-sync',
-    };
-    const result = registerDefaultWebhook(registry, 'test-plugin', config);
-
-    expect(result).toBe('custom-sync');
-    expect(registry.has('test-plugin', 'custom-sync')).toBe(true);
-  });
-
-  it('should use per-plugin path override', () => {
-    const config: DefaultWebhookHandlerConfig = {
-      enabled: true,
-      path: 'global-sync',
-      plugins: {
-        'test-plugin': { path: 'plugin-specific' },
-      },
-    };
-    const result = registerDefaultWebhook(registry, 'test-plugin', config);
-
-    expect(result).toBe('plugin-specific');
-    expect(registry.has('test-plugin', 'plugin-specific')).toBe(true);
-    expect(registry.has('test-plugin', 'global-sync')).toBe(false);
-  });
-
-  it('should use global path for plugins without override', () => {
-    const config: DefaultWebhookHandlerConfig = {
-      enabled: true,
-      path: 'global-sync',
-      plugins: {
-        'other-plugin': { path: 'other-path' },
-      },
-    };
-    const result = registerDefaultWebhook(registry, 'test-plugin', config);
-
-    expect(result).toBe('global-sync');
-    expect(registry.has('test-plugin', 'global-sync')).toBe(true);
-  });
-
-  it('should not register if plugin is explicitly disabled', () => {
-    const config: DefaultWebhookHandlerConfig = {
-      enabled: true,
-      plugins: {
-        'disabled-plugin': false,
-      },
-    };
-    const result = registerDefaultWebhook(registry, 'disabled-plugin', config);
-
-    expect(result).toBeNull();
-    expect(registry.size()).toBe(0);
+    expect(result).toBe(true);
+    expect(registry.has('test-plugin')).toBe(true);
     expect(consoleSpy).toHaveBeenCalledWith(
-      '📭 Default webhook disabled for plugin: disabled-plugin'
+      `📬 Default webhook registered: /_webhooks/test-plugin/${DEFAULT_WEBHOOK_PATH}`
     );
   });
 
   it('should not overwrite existing handler', () => {
     // Register a custom handler first
     registry.register('test-plugin', {
-      path: 'sync',
       handler: async () => {},
       description: 'Custom handler',
     });
 
-    const config: DefaultWebhookHandlerConfig = { enabled: true };
-    const result = registerDefaultWebhook(registry, 'test-plugin', config);
+    const result = registerDefaultWebhook(registry, 'test-plugin');
 
-    expect(result).toBeNull();
+    expect(result).toBe(false);
     // Verify original handler is preserved
-    const handler = registry.getHandler('test-plugin', 'sync');
+    const handler = registry.getHandler('test-plugin');
     expect(handler?.description).toBe('Custom handler');
     expect(consoleSpy).toHaveBeenCalledWith(
-      "📌 Plugin test-plugin already has handler for 'sync', skipping default registration"
+      `📌 Plugin test-plugin already has handler, skipping default registration`
     );
   });
 
   it('should register handler with correct description', () => {
-    const config: DefaultWebhookHandlerConfig = { enabled: true };
-    registerDefaultWebhook(registry, 'my-plugin', config);
+    registerDefaultWebhook(registry, 'my-plugin');
 
-    const handler = registry.getHandler('my-plugin', 'sync');
+    const handler = registry.getHandler('my-plugin');
     expect(handler?.description).toBe('Default UDL sync handler for my-plugin');
   });
+
+  it('should include idField in description when provided', () => {
+    registerDefaultWebhook(registry, 'my-plugin', 'externalId');
+
+    const handler = registry.getHandler('my-plugin');
+    expect(handler?.description).toBe(
+      'Default UDL sync handler for my-plugin (idField: externalId)'
+    );
+    expect(consoleSpy).toHaveBeenCalledWith(
+      `📬 Default webhook registered: /_webhooks/my-plugin/${DEFAULT_WEBHOOK_PATH} (idField: externalId)`
+    );
+  });
+
+  it('should register for multiple plugins independently', () => {
+    registerDefaultWebhook(registry, 'plugin-a');
+    registerDefaultWebhook(registry, 'plugin-b');
+    registerDefaultWebhook(registry, 'plugin-c');
+
+    expect(registry.has('plugin-a')).toBe(true);
+    expect(registry.has('plugin-b')).toBe(true);
+    expect(registry.has('plugin-c')).toBe(true);
+    expect(registry.size()).toBe(3);
+  });
 });
 
-describe('registerDefaultWebhooks', () => {
+describe('registerPluginWebhookHandler', () => {
   let registry: WebhookRegistry;
+  let consoleSpy: ReturnType<typeof vi.spyOn>;
 
   beforeEach(() => {
     registry = new WebhookRegistry();
-    vi.spyOn(console, 'log').mockImplementation(() => {});
+    consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
   });
 
-  it('should register for multiple plugins', () => {
-    const config: DefaultWebhookHandlerConfig = { enabled: true };
-    const plugins = ['plugin-a', 'plugin-b', 'plugin-c'];
+  it('should register a custom plugin handler', () => {
+    const customHandler: PluginWebhookHandler = async () => {};
 
-    const results = registerDefaultWebhooks(registry, plugins, config);
+    const result = registerPluginWebhookHandler(
+      registry,
+      'my-plugin',
+      customHandler
+    );
 
-    expect(results.size).toBe(3);
-    expect(results.get('plugin-a')).toBe('sync');
-    expect(results.get('plugin-b')).toBe('sync');
-    expect(results.get('plugin-c')).toBe('sync');
-    expect(registry.size()).toBe(3);
+    expect(result).toBe(true);
+    expect(registry.has('my-plugin')).toBe(true);
+    expect(consoleSpy).toHaveBeenCalledWith(
+      `📬 Custom webhook registered: /_webhooks/my-plugin/${DEFAULT_WEBHOOK_PATH}`
+    );
   });
 
-  it('should handle mixed enable/disable per plugin', () => {
-    const config: DefaultWebhookHandlerConfig = {
-      enabled: true,
-      plugins: {
-        'plugin-b': false,
-      },
-    };
-    const plugins = ['plugin-a', 'plugin-b', 'plugin-c'];
+  it('should register handler with correct description', () => {
+    const customHandler: PluginWebhookHandler = async () => {};
 
-    const results = registerDefaultWebhooks(registry, plugins, config);
+    registerPluginWebhookHandler(registry, 'my-plugin', customHandler);
 
-    expect(results.get('plugin-a')).toBe('sync');
-    expect(results.get('plugin-b')).toBeNull();
-    expect(results.get('plugin-c')).toBe('sync');
-    expect(registry.size()).toBe(2);
+    const handler = registry.getHandler('my-plugin');
+    expect(handler?.description).toBe('Custom webhook handler for my-plugin');
   });
 
-  it('should handle custom paths per plugin', () => {
-    const config: DefaultWebhookHandlerConfig = {
-      enabled: true,
-      path: 'default-path',
-      plugins: {
-        'plugin-a': { path: 'path-a' },
-        'plugin-c': { path: 'path-c' },
-      },
+  it('should wrap the plugin handler to match WebhookHandlerFn signature', async () => {
+    const mockReq = {} as IncomingMessage;
+    const mockRes = {} as ServerResponse;
+    const mockContext: WebhookHandlerContext = {
+      store: {} as NodeStore,
+      actions: { createNode: vi.fn() } as unknown as NodeActions,
+      body: { test: true },
+      rawBody: Buffer.from('test'),
     };
-    const plugins = ['plugin-a', 'plugin-b', 'plugin-c'];
 
-    const results = registerDefaultWebhooks(registry, plugins, config);
-
-    expect(results.get('plugin-a')).toBe('path-a');
-    expect(results.get('plugin-b')).toBe('default-path');
-    expect(results.get('plugin-c')).toBe('path-c');
-  });
+    let receivedContext: PluginWebhookHandlerContext | null = null;
+    const customHandler: PluginWebhookHandler = async (ctx) => {
+      receivedContext = ctx;
+    };
 
-  it('should return empty results when config is undefined', () => {
-    const plugins = ['plugin-a', 'plugin-b'];
+    registerPluginWebhookHandler(registry, 'my-plugin', customHandler);
 
-    const results = registerDefaultWebhooks(registry, plugins, undefined);
+    const handler = registry.getHandler('my-plugin');
+    await handler!.handler(mockReq, mockRes, mockContext);
 
-    expect(results.size).toBe(2);
-    expect(results.get('plugin-a')).toBeNull();
-    expect(results.get('plugin-b')).toBeNull();
-    expect(registry.size()).toBe(0);
+    expect(receivedContext).toEqual({
+      req: mockReq,
+      res: mockRes,
+      actions: mockContext.actions,
+      store: mockContext.store,
+      body: mockContext.body,
+      rawBody: mockContext.rawBody,
+    });
   });
 
-  it('should handle empty plugin list', () => {
-    const config: DefaultWebhookHandlerConfig = { enabled: true };
+  it('should allow plugin handler to access node actions', async () => {
+    const mockReq = {} as IncomingMessage;
+    const mockRes = {
+      writeHead: vi.fn(),
+      end: vi.fn(),
+    } as unknown as ServerResponse;
+    const createNodeFn = vi.fn();
+    const mockContext: WebhookHandlerContext = {
+      store: {} as NodeStore,
+      actions: { createNode: createNodeFn } as unknown as NodeActions,
+      body: { nodeType: 'Test', data: { name: 'test' } },
+      rawBody: Buffer.from('test'),
+    };
+
+    const customHandler: PluginWebhookHandler = async ({ actions }) => {
+      await actions.createNode({
+        internal: { id: '1', type: 'Test', owner: 'my-plugin' },
+        name: 'test',
+      });
+    };
+
+    registerPluginWebhookHandler(registry, 'my-plugin', customHandler);
 
-    const results = registerDefaultWebhooks(registry, [], config);
+    const handler = registry.getHandler('my-plugin');
+    await handler!.handler(mockReq, mockRes, mockContext);
 
-    expect(results.size).toBe(0);
-    expect(registry.size()).toBe(0);
+    expect(createNodeFn).toHaveBeenCalledWith({
+      internal: { id: '1', type: 'Test', owner: 'my-plugin' },
+      name: 'test',
+    });
   });
 });

From c1f6708ad7158feef50a97e85947d6bdeaa0c08e Mon Sep 17 00:00:00 2001
From: dawidurbanski <hi@dawidurbanski.com>
Date: Tue, 23 Dec 2025 01:31:13 +0100
Subject: [PATCH 29/46] feat(core): add outbound webhook triggering with
 transformPayload
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Trigger outbound webhooks after batch processing to notify external
systems (Vercel deploy hooks, CI) with the "30 webhooks → 1 build"
optimization.

- OutboundWebhookManager for parallel webhook triggering
- Configurable via remote.webhooks.outbound array
- HTTP method option (POST/GET, default POST)
- transformPayload callback for custom payload shaping
- Retry logic with exponential backoff (3 retries, 1s base delay)
- Default payload includes items array with webhook details
---
 .changeset/outbound-webhook-triggering.md     |  74 +++-
 packages/core/src/start-server.ts             |  10 +-
 packages/core/src/webhooks/outbound.ts        | 137 ++++++-
 packages/core/src/webhooks/queue.ts           |   4 +-
 .../core/tests/unit/webhooks/outbound.test.ts | 352 +++++++++++++++++-
 5 files changed, 534 insertions(+), 43 deletions(-)

diff --git a/.changeset/outbound-webhook-triggering.md b/.changeset/outbound-webhook-triggering.md
index 674d9bd..f7c80cb 100644
--- a/.changeset/outbound-webhook-triggering.md
+++ b/.changeset/outbound-webhook-triggering.md
@@ -2,18 +2,20 @@
 'universal-data-layer': minor
 ---
 
-Add outbound webhook triggering after batch processing
+Add outbound webhook triggering with transformPayload support
 
-This release adds the ability to trigger outbound webhooks after a batch of incoming webhooks has been processed. This enables the "30 webhooks → 1 build" optimization by notifying external systems (e.g., Vercel deploy hooks, CI systems) once after processing a batch rather than for each individual webhook.
+Trigger outbound webhooks after a batch of incoming webhooks has been processed. This enables the "30 webhooks → 1 build" optimization by notifying external systems (e.g., Vercel deploy hooks, CI systems) once after processing a batch rather than for each individual webhook.
 
 **Features:**
 
 - `OutboundWebhookManager` class for managing outbound webhook notifications
-- Configurable outbound webhook endpoints via `remote.webhooks.trigger`
+- Configurable outbound webhook endpoints via `remote.webhooks.outbound`
+- HTTP method selection (POST or GET, default POST)
 - Retry logic with exponential backoff (default: 3 retries, 1000ms base delay)
 - Custom headers support for authentication
 - Parallel triggering to multiple endpoints using `Promise.allSettled`
-- Payload includes batch summary: webhook count, plugins, timestamp, source
+- `transformPayload` callback for customizing the payload per trigger
+- Default payload includes `items` array with webhook details
 
 **Example configuration:**
 
@@ -22,15 +24,31 @@ export const { config } = defineConfig({
   remote: {
     webhooks: {
       debounceMs: 5000,
-      trigger: [
+      outbound: [
         {
+          // Vercel just needs an empty POST body
           url: 'https://api.vercel.com/v1/integrations/deploy/...',
-          headers: { Authorization: 'Bearer token' },
-          retries: 3,
-          retryDelayMs: 1000,
+          transformPayload: () => ({}),
+        },
+        {
+          // Simple GET ping (no body needed)
+          url: 'https://my-cdn.example.com/purge',
+          method: 'GET',
+          transformPayload: () => ({}),
         },
         {
+          // Custom payload for CI system
           url: 'https://my-ci.example.com/webhook',
+          transformPayload: ({ items, timestamp }) => ({
+            event: 'content-updated',
+            changes: items.map((i) => i.body),
+            timestamp,
+          }),
+        },
+        {
+          // No transform = uses default payload with items
+          url: 'https://other.example.com/hook',
+          headers: { Authorization: 'Bearer token' },
         },
       ],
     },
@@ -38,7 +56,29 @@ export const { config } = defineConfig({
 });
 ```
 
-**Outbound webhook payload:**
+**transformPayload context:**
+
+```typescript
+type TransformPayloadContext = {
+  batch: WebhookBatch; // Raw batch data
+  event: 'batch-complete'; // Event type
+  timestamp: string; // ISO 8601 timestamp
+  source: string; // UDL instance ID
+  summary: {
+    webhookCount: number;
+    plugins: string[];
+  };
+  items: Array<{
+    // Individual webhook items
+    pluginName: string;
+    body: unknown;
+    headers: Record<string, string | string[] | undefined>;
+    timestamp: number;
+  }>;
+};
+```
+
+**Default outbound webhook payload:**
 
 ```json
 {
@@ -48,6 +88,20 @@ export const { config } = defineConfig({
     "webhookCount": 30,
     "plugins": ["@universal-data-layer/plugin-source-contentful"]
   },
-  "source": "default"
+  "source": "UDL",
+  "items": [
+    { "pluginName": "contentful", "body": { "operation": "upsert", ... } },
+    ...
+  ]
 }
 ```
+
+**Exports:**
+
+- `OutboundWebhookManager` - Class for managing outbound webhooks
+- `OutboundWebhookConfig` - Configuration type for outbound webhooks
+- `OutboundWebhookPayload` - Default payload type
+- `OutboundWebhookResult` - Result type for trigger operations
+- `TransformPayloadContext` - Context type for transformPayload function
+- `TransformPayload` - Type for the transform function
+- `WebhookItem` - Type for individual webhook item info
diff --git a/packages/core/src/start-server.ts b/packages/core/src/start-server.ts
index 590bad9..e3fbfd8 100644
--- a/packages/core/src/start-server.ts
+++ b/packages/core/src/start-server.ts
@@ -83,15 +83,15 @@ export async function startServer(options: StartServerOptions = {}) {
     setWebhookHooks(webhookConfig.hooks);
   }
 
-  // Configure outbound webhook triggers if specified
-  const outboundTriggers = webhookConfig.trigger;
-  if (outboundTriggers && outboundTriggers.length > 0) {
-    const outboundManager = new OutboundWebhookManager(outboundTriggers);
+  // Configure outbound webhooks if specified
+  const outboundWebhooks = webhookConfig.outbound;
+  if (outboundWebhooks && outboundWebhooks.length > 0) {
+    const outboundManager = new OutboundWebhookManager(outboundWebhooks);
     webhookQueue.on('webhook:batch-complete', (batch) => {
       void outboundManager.triggerAll(batch);
     });
     console.log(
-      `📤 Outbound webhooks configured: ${outboundTriggers.length} endpoint(s)`
+      `📤 Outbound webhooks configured: ${outboundWebhooks.length} endpoint(s)`
     );
   }
 
diff --git a/packages/core/src/webhooks/outbound.ts b/packages/core/src/webhooks/outbound.ts
index 9637672..db9229b 100644
--- a/packages/core/src/webhooks/outbound.ts
+++ b/packages/core/src/webhooks/outbound.ts
@@ -9,11 +9,56 @@
 import type { WebhookBatch } from './queue.js';
 
 /**
- * Configuration for an outbound webhook trigger.
+ * Individual webhook item info for transform context.
+ */
+export interface WebhookItem {
+  /** Plugin that sent the webhook */
+  pluginName: string;
+  /** Parsed body of the webhook */
+  body: unknown;
+  /** Headers from the original webhook */
+  headers: Record<string, string | string[] | undefined>;
+  /** Timestamp when webhook was received */
+  timestamp: number;
+}
+
+/**
+ * Context passed to transformPayload function.
+ */
+export interface TransformPayloadContext {
+  /** Raw batch data - full access */
+  batch: WebhookBatch;
+  /** Event type */
+  event: 'batch-complete';
+  /** Timestamp of batch completion (ISO 8601) */
+  timestamp: string;
+  /** UDL instance identifier */
+  source: string;
+  /** Summary statistics */
+  summary: {
+    webhookCount: number;
+    plugins: string[];
+  };
+  /** Individual items with their payloads */
+  items: WebhookItem[];
+}
+
+/**
+ * Transform function to customize outbound webhook payload.
+ */
+export type TransformPayload = (context: TransformPayloadContext) => unknown;
+
+/**
+ * Configuration for an outbound webhook.
  */
 export interface OutboundWebhookConfig {
-  /** URL to POST to */
+  /** URL to send the webhook to */
   url: string;
+  /**
+   * HTTP method to use.
+   * @default 'POST'
+   */
+  method?: 'POST' | 'GET';
   /**
    * Events to trigger on. '*' = all events.
    * @default ['*']
@@ -32,10 +77,29 @@ export interface OutboundWebhookConfig {
    * @default 1000
    */
   retryDelayMs?: number;
+  /**
+   * Transform the payload before sending.
+   * If not provided, uses the default OutboundWebhookPayload format.
+   * Works with both POST and GET methods.
+   *
+   * @example
+   * ```typescript
+   * // Return empty object for Vercel deploy hooks
+   * transformPayload: () => ({})
+   *
+   * // Custom shape for your system
+   * transformPayload: ({ items, timestamp }) => ({
+   *   event: 'content-updated',
+   *   changes: items.map(i => i.body),
+   *   timestamp,
+   * })
+   * ```
+   */
+  transformPayload?: TransformPayload;
 }
 
 /**
- * Payload sent to outbound webhook endpoints.
+ * Payload sent to outbound webhook endpoints (default format).
  */
 export interface OutboundWebhookPayload {
   /** Event type */
@@ -48,11 +112,14 @@ export interface OutboundWebhookPayload {
     webhookCount: number;
     /** Plugins that were updated */
     plugins: string[];
-    /** Node types that were updated (if available) */
-    nodeTypes?: string[];
   };
   /** UDL instance identifier (for multi-instance setups) */
   source: string;
+  /** Individual webhook items in the batch */
+  items: Array<{
+    pluginName: string;
+    body: unknown;
+  }>;
 }
 
 /**
@@ -106,11 +173,7 @@ export class OutboundWebhookManager {
       return [];
     }
 
-    const payload = this.createPayload(batch);
-
-    const promises = this.configs.map((config) =>
-      this.trigger(config, payload)
-    );
+    const promises = this.configs.map((config) => this.trigger(config, batch));
 
     const settledResults = await Promise.allSettled(promises);
 
@@ -153,21 +216,28 @@ export class OutboundWebhookManager {
    * Trigger a single outbound webhook with retry logic.
    *
    * @param config - The webhook configuration
-   * @param payload - The payload to send
+   * @param batch - The webhook batch to send
    * @returns The result of the trigger attempt
    */
   private async trigger(
     config: OutboundWebhookConfig,
-    payload: OutboundWebhookPayload
+    batch: WebhookBatch
   ): Promise<OutboundWebhookResult> {
-    const { url, headers = {}, retries = 3, retryDelayMs = 1000 } = config;
+    const {
+      url,
+      method = 'POST',
+      headers = {},
+      retries = 3,
+      retryDelayMs = 1000,
+    } = config;
+    const payload = this.createPayload(config, batch);
 
     let lastError: Error | undefined;
 
     for (let attempt = 0; attempt <= retries; attempt++) {
       try {
         const response = await fetch(url, {
-          method: 'POST',
+          method,
           headers: {
             'Content-Type': 'application/json',
             'User-Agent': 'UDL-Webhook/1.0',
@@ -208,23 +278,56 @@ export class OutboundWebhookManager {
 
   /**
    * Create the outbound webhook payload from a batch.
+   * Uses transformPayload if provided, otherwise returns default payload.
    *
+   * @param config - The webhook configuration (may include transformPayload)
    * @param batch - The completed webhook batch
    * @returns The payload to send
    */
-  private createPayload(batch: WebhookBatch): OutboundWebhookPayload {
+  private createPayload(
+    config: OutboundWebhookConfig,
+    batch: WebhookBatch
+  ): unknown {
     // Extract unique plugin names from the batch
     const plugins = [...new Set(batch.webhooks.map((w) => w.pluginName))];
 
-    return {
+    // Build items array with relevant info
+    const items: WebhookItem[] = batch.webhooks.map((w) => ({
+      pluginName: w.pluginName,
+      body: w.body,
+      headers: w.headers,
+      timestamp: w.timestamp,
+    }));
+
+    // Build the full context
+    const context: TransformPayloadContext = {
+      batch,
       event: 'batch-complete',
       timestamp: new Date(batch.completedAt).toISOString(),
+      source: process.env['UDL_INSTANCE_ID'] || 'UDL',
       summary: {
         webhookCount: batch.webhooks.length,
         plugins,
       },
-      source: process.env['UDL_INSTANCE_ID'] || 'default',
+      items,
     };
+
+    // Use transformPayload if provided
+    if (config.transformPayload) {
+      return config.transformPayload(context);
+    }
+
+    // Default payload with items
+    return {
+      event: context.event,
+      timestamp: context.timestamp,
+      summary: context.summary,
+      source: context.source,
+      items: items.map((i) => ({
+        pluginName: i.pluginName,
+        body: i.body,
+      })),
+    } satisfies OutboundWebhookPayload;
   }
 
   /**
diff --git a/packages/core/src/webhooks/queue.ts b/packages/core/src/webhooks/queue.ts
index e09ea1b..6dc7db0 100644
--- a/packages/core/src/webhooks/queue.ts
+++ b/packages/core/src/webhooks/queue.ts
@@ -13,8 +13,6 @@ import { EventEmitter } from 'node:events';
 export interface QueuedWebhook {
   /** Name of the plugin that registered this webhook handler */
   pluginName: string;
-  /** The webhook path within the plugin */
-  path: string;
   /** Raw request body buffer */
   rawBody: Buffer;
   /** Parsed JSON body (if applicable) */
@@ -141,7 +139,7 @@ export class WebhookQueue extends EventEmitter {
   enqueue(webhook: QueuedWebhook): void {
     this.queue.push(webhook);
     console.log(
-      `📥 Webhook queued: ${webhook.pluginName}/${webhook.path} (${this.queue.length} in queue)`
+      `📥 Webhook queued: ${webhook.pluginName} (${this.queue.length} in queue)`
     );
 
     // Check if we've hit max queue size
diff --git a/packages/core/tests/unit/webhooks/outbound.test.ts b/packages/core/tests/unit/webhooks/outbound.test.ts
index c014bf8..3e431b7 100644
--- a/packages/core/tests/unit/webhooks/outbound.test.ts
+++ b/packages/core/tests/unit/webhooks/outbound.test.ts
@@ -4,6 +4,7 @@ import {
   type OutboundWebhookConfig,
   type WebhookBatch,
   type QueuedWebhook,
+  type TransformPayloadContext,
 } from '@/webhooks/index.js';
 
 // Helper to create a mock webhook batch
@@ -15,9 +16,8 @@ function createMockBatch(
   for (let i = 0; i < webhookCount; i++) {
     webhooks.push({
       pluginName: plugins[i % plugins.length]!,
-      path: `path-${i}`,
       rawBody: Buffer.from('{}'),
-      body: {},
+      body: { operation: 'upsert', nodeId: `node-${i}` },
       headers: { 'content-type': 'application/json' },
       timestamp: Date.now(),
     });
@@ -128,7 +128,7 @@ describe('OutboundWebhookManager', () => {
       expect(fetchMock).toHaveBeenCalledTimes(3);
     });
 
-    it('should send correct payload structure', async () => {
+    it('should send correct payload structure with items', async () => {
       fetchMock.mockResolvedValueOnce({
         ok: true,
         status: 200,
@@ -162,6 +162,11 @@ describe('OutboundWebhookManager', () => {
       expect(body.summary.plugins).toContain('plugin-a');
       expect(body.summary.plugins).toContain('plugin-b');
       expect(body.source).toBeDefined();
+      // New: items should be included
+      expect(body.items).toBeDefined();
+      expect(body.items.length).toBe(3);
+      expect(body.items[0]).toHaveProperty('pluginName');
+      expect(body.items[0]).toHaveProperty('body');
     });
 
     it('should include custom headers in request', async () => {
@@ -251,7 +256,6 @@ describe('OutboundWebhookManager', () => {
         webhooks: [
           {
             pluginName: 'plugin-a',
-            path: 'path-1',
             rawBody: Buffer.from('{}'),
             body: {},
             headers: {},
@@ -259,7 +263,6 @@ describe('OutboundWebhookManager', () => {
           },
           {
             pluginName: 'plugin-a',
-            path: 'path-2',
             rawBody: Buffer.from('{}'),
             body: {},
             headers: {},
@@ -267,7 +270,6 @@ describe('OutboundWebhookManager', () => {
           },
           {
             pluginName: 'plugin-b',
-            path: 'path-3',
             rawBody: Buffer.from('{}'),
             body: {},
             headers: {},
@@ -288,6 +290,340 @@ describe('OutboundWebhookManager', () => {
     });
   });
 
+  describe('transformPayload', () => {
+    it('should use default payload when no transformPayload provided', async () => {
+      fetchMock.mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        statusText: 'OK',
+      });
+
+      const manager = new OutboundWebhookManager([
+        { url: 'https://example.com/webhook' },
+      ]);
+      const batch = createMockBatch(2);
+
+      await manager.triggerAll(batch);
+
+      const callArgs = fetchMock.mock.calls[0]!;
+      const body = JSON.parse((callArgs[1] as { body: string }).body);
+
+      expect(body.event).toBe('batch-complete');
+      expect(body.timestamp).toBeDefined();
+      expect(body.summary).toBeDefined();
+      expect(body.source).toBeDefined();
+      expect(body.items).toHaveLength(2);
+    });
+
+    it('should call transformPayload with full context', async () => {
+      let receivedContext: TransformPayloadContext | undefined;
+
+      fetchMock.mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        statusText: 'OK',
+      });
+
+      const manager = new OutboundWebhookManager([
+        {
+          url: 'https://example.com/webhook',
+          transformPayload: (ctx) => {
+            receivedContext = ctx;
+            return {};
+          },
+        },
+      ]);
+
+      const batch = createMockBatch(2, ['plugin-a', 'plugin-b']);
+      await manager.triggerAll(batch);
+
+      expect(receivedContext).toBeDefined();
+      expect(receivedContext!.batch).toBe(batch);
+      expect(receivedContext!.event).toBe('batch-complete');
+      expect(receivedContext!.timestamp).toBeDefined();
+      expect(receivedContext!.source).toBeDefined();
+      expect(receivedContext!.summary.webhookCount).toBe(2);
+      expect(receivedContext!.summary.plugins).toContain('plugin-a');
+      expect(receivedContext!.summary.plugins).toContain('plugin-b');
+      expect(receivedContext!.items).toHaveLength(2);
+      expect(receivedContext!.items[0]).toHaveProperty('pluginName');
+      expect(receivedContext!.items[0]).toHaveProperty('body');
+      expect(receivedContext!.items[0]).toHaveProperty('headers');
+      expect(receivedContext!.items[0]).toHaveProperty('timestamp');
+    });
+
+    it('should allow transformPayload to return empty object', async () => {
+      fetchMock.mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        statusText: 'OK',
+      });
+
+      const manager = new OutboundWebhookManager([
+        {
+          url: 'https://api.vercel.com/deploy',
+          transformPayload: () => ({}),
+        },
+      ]);
+      const batch = createMockBatch(3);
+
+      await manager.triggerAll(batch);
+
+      const callArgs = fetchMock.mock.calls[0]!;
+      const body = JSON.parse((callArgs[1] as { body: string }).body);
+
+      expect(body).toEqual({});
+    });
+
+    it('should allow transformPayload to return custom shape', async () => {
+      fetchMock.mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        statusText: 'OK',
+      });
+
+      const manager = new OutboundWebhookManager([
+        {
+          url: 'https://my-ci.example.com/webhook',
+          transformPayload: ({ items, timestamp }) => ({
+            event: 'content-updated',
+            changes: items.map((i) => i.body),
+            deployedAt: timestamp,
+          }),
+        },
+      ]);
+      const batch = createMockBatch(2);
+
+      await manager.triggerAll(batch);
+
+      const callArgs = fetchMock.mock.calls[0]!;
+      const body = JSON.parse((callArgs[1] as { body: string }).body);
+
+      expect(body.event).toBe('content-updated');
+      expect(body.changes).toHaveLength(2);
+      expect(body.deployedAt).toBeDefined();
+      // Original fields should not be present
+      expect(body.summary).toBeUndefined();
+      expect(body.source).toBeUndefined();
+    });
+
+    it('should use convenience values from context', async () => {
+      fetchMock.mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        statusText: 'OK',
+      });
+
+      const manager = new OutboundWebhookManager([
+        {
+          url: 'https://example.com/webhook',
+          transformPayload: ({ timestamp, summary }) => ({
+            deployedAt: timestamp,
+            changedCount: summary.webhookCount,
+            plugins: summary.plugins,
+          }),
+        },
+      ]);
+      const batch = createMockBatch(3, ['plugin-a']);
+
+      await manager.triggerAll(batch);
+
+      const callArgs = fetchMock.mock.calls[0]!;
+      const body = JSON.parse((callArgs[1] as { body: string }).body);
+
+      expect(body.changedCount).toBe(3);
+      expect(body.plugins).toEqual(['plugin-a']);
+    });
+
+    it('should allow different transforms per trigger', async () => {
+      fetchMock.mockResolvedValue({
+        ok: true,
+        status: 200,
+        statusText: 'OK',
+      });
+
+      const manager = new OutboundWebhookManager([
+        {
+          url: 'https://vercel.com/deploy',
+          transformPayload: () => ({}),
+        },
+        {
+          url: 'https://ci.example.com/webhook',
+          transformPayload: ({ summary }) => ({
+            count: summary.webhookCount,
+          }),
+        },
+        {
+          url: 'https://default.example.com/webhook',
+          // No transform - uses default
+        },
+      ]);
+      const batch = createMockBatch(2);
+
+      await manager.triggerAll(batch);
+
+      expect(fetchMock).toHaveBeenCalledTimes(3);
+
+      // First call: empty object
+      const body1 = JSON.parse(
+        (fetchMock.mock.calls[0]![1] as { body: string }).body
+      );
+      expect(body1).toEqual({});
+
+      // Second call: custom shape
+      const body2 = JSON.parse(
+        (fetchMock.mock.calls[1]![1] as { body: string }).body
+      );
+      expect(body2).toEqual({ count: 2 });
+
+      // Third call: default payload
+      const body3 = JSON.parse(
+        (fetchMock.mock.calls[2]![1] as { body: string }).body
+      );
+      expect(body3.event).toBe('batch-complete');
+      expect(body3.items).toBeDefined();
+    });
+
+    it('should include headers in items', async () => {
+      let receivedItems: TransformPayloadContext['items'] = [];
+
+      fetchMock.mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        statusText: 'OK',
+      });
+
+      const manager = new OutboundWebhookManager([
+        {
+          url: 'https://example.com/webhook',
+          transformPayload: ({ items }) => {
+            receivedItems = items;
+            return {};
+          },
+        },
+      ]);
+
+      const batch: WebhookBatch = {
+        webhooks: [
+          {
+            pluginName: 'test',
+            rawBody: Buffer.from('{}'),
+            body: { data: 'test' },
+            headers: {
+              'x-signature': 'abc123',
+              'content-type': 'application/json',
+            },
+            timestamp: 1234567890,
+          },
+        ],
+        startedAt: Date.now() - 100,
+        completedAt: Date.now(),
+      };
+
+      await manager.triggerAll(batch);
+
+      expect(receivedItems[0]!.headers['x-signature']).toBe('abc123');
+      expect(receivedItems[0]!.headers['content-type']).toBe(
+        'application/json'
+      );
+    });
+  });
+
+  describe('method option', () => {
+    it('should use POST by default', async () => {
+      fetchMock.mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        statusText: 'OK',
+      });
+
+      const manager = new OutboundWebhookManager([
+        { url: 'https://example.com/webhook' },
+      ]);
+      const batch = createMockBatch(1);
+
+      await manager.triggerAll(batch);
+
+      expect(fetchMock).toHaveBeenCalledWith(
+        'https://example.com/webhook',
+        expect.objectContaining({
+          method: 'POST',
+        })
+      );
+    });
+
+    it('should use GET when specified', async () => {
+      fetchMock.mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        statusText: 'OK',
+      });
+
+      const manager = new OutboundWebhookManager([
+        { url: 'https://example.com/ping', method: 'GET' },
+      ]);
+      const batch = createMockBatch(1);
+
+      await manager.triggerAll(batch);
+
+      expect(fetchMock).toHaveBeenCalledWith(
+        'https://example.com/ping',
+        expect.objectContaining({
+          method: 'GET',
+        })
+      );
+    });
+
+    it('should send body with GET request', async () => {
+      fetchMock.mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        statusText: 'OK',
+      });
+
+      const manager = new OutboundWebhookManager([
+        { url: 'https://example.com/ping', method: 'GET' },
+      ]);
+      const batch = createMockBatch(1);
+
+      await manager.triggerAll(batch);
+
+      const callArgs = fetchMock.mock.calls[0]!;
+      const options = callArgs[1] as { method: string; body: string };
+
+      expect(options.method).toBe('GET');
+      expect(options.body).toBeDefined();
+      const body = JSON.parse(options.body);
+      expect(body.event).toBe('batch-complete');
+    });
+
+    it('should allow GET with transformPayload', async () => {
+      fetchMock.mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        statusText: 'OK',
+      });
+
+      const manager = new OutboundWebhookManager([
+        {
+          url: 'https://example.com/ping',
+          method: 'GET',
+          transformPayload: () => ({ ping: true }),
+        },
+      ]);
+      const batch = createMockBatch(1);
+
+      await manager.triggerAll(batch);
+
+      const callArgs = fetchMock.mock.calls[0]!;
+      const options = callArgs[1] as { method: string; body: string };
+
+      expect(options.method).toBe('GET');
+      const body = JSON.parse(options.body);
+      expect(body).toEqual({ ping: true });
+    });
+  });
+
   describe('retry logic', () => {
     it('should retry on failure', async () => {
       fetchMock
@@ -418,7 +754,7 @@ describe('OutboundWebhookManager', () => {
       }
     });
 
-    it('should use "default" if UDL_INSTANCE_ID is not set', async () => {
+    it('should use "UDL" if UDL_INSTANCE_ID is not set', async () => {
       const originalEnv = process.env['UDL_INSTANCE_ID'];
       delete process.env['UDL_INSTANCE_ID'];
 
@@ -438,7 +774,7 @@ describe('OutboundWebhookManager', () => {
       const callArgs = fetchMock.mock.calls[0]!;
       const body = JSON.parse((callArgs[1] as { body: string }).body);
 
-      expect(body.source).toBe('default');
+      expect(body.source).toBe('UDL');
 
       // Restore
       if (originalEnv !== undefined) {

From c86fa5c4892c7362c5d97416d06e9ac7c92c138e Mon Sep 17 00:00:00 2001
From: dawidurbanski <hi@dawidurbanski.com>
Date: Tue, 23 Dec 2025 01:31:22 +0100
Subject: [PATCH 30/46] test(adapter-nextjs): update tests for UDL default port
 behavior

Update dev and start command tests to reflect that UDL now uses its
own default port from config rather than requiring explicit --port flag.
---
 packages/adapter-nextjs/tests/unit/dev.test.ts   | 5 +++--
 packages/adapter-nextjs/tests/unit/start.test.ts | 5 +++--
 2 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/packages/adapter-nextjs/tests/unit/dev.test.ts b/packages/adapter-nextjs/tests/unit/dev.test.ts
index f35d2b8..bbf7dbe 100644
--- a/packages/adapter-nextjs/tests/unit/dev.test.ts
+++ b/packages/adapter-nextjs/tests/unit/dev.test.ts
@@ -94,7 +94,7 @@ describe('runDev', () => {
     vi.restoreAllMocks();
   });
 
-  it('should spawn UDL with default port', async () => {
+  it('should spawn UDL without explicit port (uses UDL default)', async () => {
     const devPromise = runDev({}, [], {
       exit: mockExit,
       signal: abortController.signal,
@@ -104,9 +104,10 @@ describe('runDev', () => {
     signalHandlers.get('SIGINT')?.();
     await devPromise;
 
+    // When no port is specified, UDL uses its own default (from config or 4000)
     expect(mockSpawnWithPrefix).toHaveBeenCalledWith(
       'npx',
-      ['universal-data-layer', '--port', '4000'],
+      ['universal-data-layer'],
       expect.stringContaining('[udl]')
     );
   });
diff --git a/packages/adapter-nextjs/tests/unit/start.test.ts b/packages/adapter-nextjs/tests/unit/start.test.ts
index a831c19..771d9c3 100644
--- a/packages/adapter-nextjs/tests/unit/start.test.ts
+++ b/packages/adapter-nextjs/tests/unit/start.test.ts
@@ -94,7 +94,7 @@ describe('runStart', () => {
     vi.restoreAllMocks();
   });
 
-  it('should spawn UDL with default port', async () => {
+  it('should spawn UDL without explicit port (uses UDL default)', async () => {
     const startPromise = runStart({}, [], {
       exit: mockExit,
       signal: abortController.signal,
@@ -104,9 +104,10 @@ describe('runStart', () => {
     signalHandlers.get('SIGINT')?.();
     await startPromise;
 
+    // When no port is specified, UDL uses its own default (from config or 4000)
     expect(mockSpawnWithPrefix).toHaveBeenCalledWith(
       'npx',
-      ['universal-data-layer', '--port', '4000'],
+      ['universal-data-layer'],
       expect.stringContaining('[udl]')
     );
   });

From e7f7f86231a682965ee9e19f49c37d4a88c1d748 Mon Sep 17 00:00:00 2001
From: dawidurbanski <hi@dawidurbanski.com>
Date: Tue, 23 Dec 2025 01:35:35 +0100
Subject: [PATCH 31/46] chore: improve test coverage script to handle exit
 codes

---
 package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/package.json b/package.json
index c519e2d..66325a0 100644
--- a/package.json
+++ b/package.json
@@ -14,7 +14,7 @@
     "lint": "turbo lint --filter='./packages/*' --ui=stream",
     "fix": "turbo fix --filter='./packages/*' && npm run fix --prefix tests/manual",
     "test": "turbo test --filter='./packages/*' --ui=stream",
-    "test:coverage": "turbo test:coverage --filter='./packages/*' --ui=stream && node scripts/generate-coverage-index.js && node scripts/inject-coverage-nav.js",
+    "test:coverage": "turbo test:coverage --filter='./packages/*' --ui=stream; exitcode=$?; node scripts/generate-coverage-index.js && node scripts/inject-coverage-nav.js; exit $exitcode",
     "test:coverage:file": "npm run test:coverage:file --workspace=universal-data-layer --",
     "codegen": "turbo codegen --filter='./packages/*' --ui=stream",
     "typecheck": "turbo typecheck --filter='./packages/*' --ui=stream && npm run typecheck --prefix tests/manual",

From b67b4fd8eb42da4565d19e4bd1f1a1bac5a6500e Mon Sep 17 00:00:00 2001
From: dawidurbanski <hi@dawidurbanski.com>
Date: Tue, 23 Dec 2025 02:45:58 +0100
Subject: [PATCH 32/46] test(core): add comprehensive test coverage

- Add unit tests for webhook processor, outbound, queue, and default handler
- Add websocket server and client unit tests with coverage ignore markers
- Add remote sync unit tests
- Add node actions unit tests
- Expand integration tests for loader
- Add coverage ignore comments for unreachable code paths
---
 coverage/base.css                             |   2 +
 packages/core/src/websocket/server.ts         |   5 +-
 .../core/tests/integration/loader.test.ts     | 187 +++++
 .../unit/nodes/actions/nodeActions.test.ts    | 306 ++++++++
 packages/core/tests/unit/sync/remote.test.ts  | 330 ++++++++
 .../unit/webhooks/default-handler.test.ts     | 219 +++++-
 .../core/tests/unit/webhooks/outbound.test.ts |  82 ++
 .../tests/unit/webhooks/processor.test.ts     | 576 ++++++++++++++
 .../core/tests/unit/webhooks/queue.test.ts    |  26 +
 .../core/tests/unit/websocket/client.test.ts  | 709 ++++++++++++++++++
 .../core/tests/unit/websocket/server.test.ts  | 231 ++++++
 11 files changed, 2660 insertions(+), 13 deletions(-)
 create mode 100644 packages/core/tests/unit/nodes/actions/nodeActions.test.ts
 create mode 100644 packages/core/tests/unit/sync/remote.test.ts
 create mode 100644 packages/core/tests/unit/webhooks/processor.test.ts
 create mode 100644 packages/core/tests/unit/websocket/client.test.ts

diff --git a/coverage/base.css b/coverage/base.css
index 16e5341..f418035 100644
--- a/coverage/base.css
+++ b/coverage/base.css
@@ -129,12 +129,14 @@ table.coverage td span.cline-any {
   white-space: nowrap;
 }
 .coverage-summary th.file { border-right: none !important; }
+.coverage-summary th.pct { }
 .coverage-summary th.pic,
 .coverage-summary th.abs,
 .coverage-summary td.pct,
 .coverage-summary td.abs { text-align: right; }
 .coverage-summary td.file { white-space: nowrap;  }
 .coverage-summary td.pic { min-width: 120px !important;  }
+.coverage-summary tfoot td { }
 
 .coverage-summary .sorter {
     height: 10px;
diff --git a/packages/core/src/websocket/server.ts b/packages/core/src/websocket/server.ts
index 99d4011..e9c412a 100644
--- a/packages/core/src/websocket/server.ts
+++ b/packages/core/src/websocket/server.ts
@@ -146,13 +146,15 @@ export class UDLWebSocketServer {
       });
     }, heartbeatIntervalMs);
 
-    // Clean up heartbeat on server close
+    // Clean up heartbeat on server close (backup cleanup - normally cleared in close())
+    /* v8 ignore start */
     this.wss.on('close', () => {
       if (this.heartbeatInterval) {
         clearInterval(this.heartbeatInterval);
         this.heartbeatInterval = null;
       }
     });
+    /* v8 ignore stop */
 
     // Subscribe to node events
     this.nodeEventHandler = (event: NodeChangeEvent) => {
@@ -239,6 +241,7 @@ export class UDLWebSocketServer {
 
     this.wss.clients.forEach((ws) => {
       const trackedWs = ws as TrackedWebSocket;
+      /* v8 ignore next 3 - ws library removes closed clients from Set */
       if (trackedWs.readyState !== WebSocket.OPEN) {
         return;
       }
diff --git a/packages/core/tests/integration/loader.test.ts b/packages/core/tests/integration/loader.test.ts
index 5f74ff9..4cfa42c 100644
--- a/packages/core/tests/integration/loader.test.ts
+++ b/packages/core/tests/integration/loader.test.ts
@@ -1532,4 +1532,191 @@ describe('loader integration tests', () => {
       delete global.__childCacheDir;
     });
   });
+
+  describe('loadPlugins webhook and idField handling', () => {
+    it('should include idField in indexes when plugin config has idField defined', async () => {
+      const pluginDir = join(pluginsDir, 'idfield-plugin');
+      mkdirSync(pluginDir, { recursive: true });
+
+      writeFileSync(
+        join(pluginDir, 'udl.config.js'),
+        `
+        export const config = {
+          name: 'idfield-plugin',
+          idField: 'externalId' // This idField should be auto-indexed
+        };
+
+        export async function sourceNodes({ actions, createNodeId }) {
+          await actions.createNode({
+            internal: {
+              id: createNodeId('IdFieldNode', '1'),
+              type: 'IdFieldNode',
+            },
+            externalId: 'ext-123',
+            parent: undefined,
+            children: undefined,
+          });
+        }
+        `
+      );
+
+      const { NodeStore } = await import('@/nodes/index.js');
+      const consoleLogSpy = vi
+        .spyOn(console, 'log')
+        .mockImplementation(() => {});
+
+      const store = new NodeStore();
+      await loadPlugins([pluginDir], {
+        appConfig: {},
+        store,
+        cache: false,
+      });
+
+      // Verify the node was created
+      expect(store.getAll()).toHaveLength(1);
+
+      // Verify the idField was auto-indexed
+      const registeredIndexes = store.getRegisteredIndexes('IdFieldNode');
+      expect(registeredIndexes).toContain('externalId');
+
+      // Verify we can look up by the idField
+      const byExternalId = store.getByField(
+        'IdFieldNode',
+        'externalId',
+        'ext-123'
+      );
+      expect(byExternalId).toBeDefined();
+      expect(
+        (byExternalId as unknown as Record<string, unknown>)?.['externalId']
+      ).toBe('ext-123');
+
+      consoleLogSpy.mockRestore();
+    });
+
+    it('should use custom registerWebhookHandler when plugin exports it', async () => {
+      const { WebhookRegistry } = await import('@/webhooks/registry.js');
+
+      const pluginDir = join(pluginsDir, 'custom-webhook-plugin');
+      mkdirSync(pluginDir, { recursive: true });
+
+      writeFileSync(
+        join(pluginDir, 'udl.config.js'),
+        `
+        export const config = {
+          name: 'custom-webhook-plugin'
+        };
+
+        export async function sourceNodes({ actions, createNodeId }) {
+          await actions.createNode({
+            internal: {
+              id: createNodeId('WebhookNode', '1'),
+              type: 'WebhookNode',
+            },
+            parent: undefined,
+            children: undefined,
+          });
+        }
+
+        // Custom webhook handler - should be used instead of default
+        export async function registerWebhookHandler({ req, res, actions, body }) {
+          // Custom handling logic
+          res.writeHead(200);
+          res.end('Custom handler');
+        }
+        `
+      );
+
+      const { NodeStore } = await import('@/nodes/index.js');
+      const consoleLogSpy = vi
+        .spyOn(console, 'log')
+        .mockImplementation(() => {});
+
+      const store = new NodeStore();
+      const webhookRegistry = new WebhookRegistry();
+
+      await loadPlugins([pluginDir], {
+        appConfig: {},
+        store,
+        cache: false,
+        webhookRegistry,
+      });
+
+      // Verify the custom handler was registered
+      expect(webhookRegistry.has('custom-webhook-plugin')).toBe(true);
+
+      const handler = webhookRegistry.getHandler('custom-webhook-plugin');
+      expect(handler).toBeDefined();
+      expect(handler?.description).toBe(
+        'Custom webhook handler for custom-webhook-plugin'
+      );
+
+      // Verify console log was called for custom handler registration
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        expect.stringContaining('Custom webhook registered')
+      );
+
+      consoleLogSpy.mockRestore();
+    });
+
+    it('should use default webhook handler when plugin does not export registerWebhookHandler', async () => {
+      const { WebhookRegistry } = await import('@/webhooks/registry.js');
+
+      const pluginDir = join(pluginsDir, 'default-webhook-plugin');
+      mkdirSync(pluginDir, { recursive: true });
+
+      writeFileSync(
+        join(pluginDir, 'udl.config.js'),
+        `
+        export const config = {
+          name: 'default-webhook-plugin',
+          idField: 'myId'
+        };
+
+        export async function sourceNodes({ actions, createNodeId }) {
+          await actions.createNode({
+            internal: {
+              id: createNodeId('DefaultWebhookNode', '1'),
+              type: 'DefaultWebhookNode',
+            },
+            myId: 'my-123',
+            parent: undefined,
+            children: undefined,
+          });
+        }
+        // No registerWebhookHandler export - should use default
+        `
+      );
+
+      const { NodeStore } = await import('@/nodes/index.js');
+      const consoleLogSpy = vi
+        .spyOn(console, 'log')
+        .mockImplementation(() => {});
+
+      const store = new NodeStore();
+      const webhookRegistry = new WebhookRegistry();
+
+      await loadPlugins([pluginDir], {
+        appConfig: {},
+        store,
+        cache: false,
+        webhookRegistry,
+      });
+
+      // Verify the default handler was registered
+      expect(webhookRegistry.has('default-webhook-plugin')).toBe(true);
+
+      const handler = webhookRegistry.getHandler('default-webhook-plugin');
+      expect(handler).toBeDefined();
+      expect(handler?.description).toBe(
+        'Default UDL sync handler for default-webhook-plugin (idField: myId)'
+      );
+
+      // Verify console log was called for default handler registration
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        expect.stringContaining('Default webhook registered')
+      );
+
+      consoleLogSpy.mockRestore();
+    });
+  });
 });
diff --git a/packages/core/tests/unit/nodes/actions/nodeActions.test.ts b/packages/core/tests/unit/nodes/actions/nodeActions.test.ts
new file mode 100644
index 0000000..ceca21e
--- /dev/null
+++ b/packages/core/tests/unit/nodes/actions/nodeActions.test.ts
@@ -0,0 +1,306 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { createNodeActions } from '@/nodes/actions/nodeActions.js';
+import type { NodeStore } from '@/nodes/store.js';
+import type { DeletionLog } from '@/sync/index.js';
+import type { Node } from '@/nodes/types.js';
+import type { CreateNodeInput } from '@/nodes/actions/createNode.js';
+import * as createNodeModule from '@/nodes/actions/createNode.js';
+import * as deleteNodeModule from '@/nodes/actions/deleteNode.js';
+import * as extendNodeModule from '@/nodes/actions/extendNode.js';
+import * as queriesModule from '@/nodes/queries.js';
+
+// Mock dependencies
+vi.mock('@/nodes/actions/createNode.js', () => ({
+  createNode: vi.fn(),
+}));
+
+vi.mock('@/nodes/actions/deleteNode.js', () => ({
+  deleteNode: vi.fn(),
+}));
+
+vi.mock('@/nodes/actions/extendNode.js', () => ({
+  extendNode: vi.fn(),
+}));
+
+vi.mock('@/nodes/queries.js', () => ({
+  getNode: vi.fn(),
+  getNodes: vi.fn(),
+  getNodesByType: vi.fn(),
+}));
+
+describe('createNodeActions', () => {
+  let mockStore: NodeStore;
+  let mockDeletionLog: DeletionLog;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockStore = {} as NodeStore;
+    mockDeletionLog = {
+      add: vi.fn(),
+      getDeletedSince: vi.fn(),
+      clear: vi.fn(),
+    } as unknown as DeletionLog;
+  });
+
+  describe('createNode', () => {
+    it('delegates to createNode with store and owner', async () => {
+      const mockNode = { id: 'test-1', internal: { type: 'TestType' } };
+      vi.mocked(createNodeModule.createNode).mockResolvedValue(
+        mockNode as never
+      );
+
+      const actions = createNodeActions({
+        store: mockStore,
+        owner: 'test-plugin',
+      });
+
+      const input: CreateNodeInput = {
+        id: 'test-1',
+        internal: { id: 'test-1', type: 'TestType', owner: 'test-plugin' },
+      };
+      const result = await actions.createNode(input);
+
+      expect(createNodeModule.createNode).toHaveBeenCalledWith(input, {
+        store: mockStore,
+        owner: 'test-plugin',
+      });
+      expect(result).toBe(mockNode);
+    });
+
+    it('passes additional options to createNode', async () => {
+      const mockNode = { id: 'test-1', internal: { type: 'TestType' } };
+      vi.mocked(createNodeModule.createNode).mockResolvedValue(
+        mockNode as never
+      );
+
+      const actions = createNodeActions({
+        store: mockStore,
+        owner: 'test-plugin',
+      });
+
+      const input: CreateNodeInput = {
+        id: 'test-1',
+        internal: { id: 'test-1', type: 'TestType', owner: 'test-plugin' },
+      };
+      const schema = { override: vi.fn() };
+      await actions.createNode(input, { schema } as never);
+
+      expect(createNodeModule.createNode).toHaveBeenCalledWith(input, {
+        store: mockStore,
+        owner: 'test-plugin',
+        schema,
+      });
+    });
+  });
+
+  describe('deleteNode', () => {
+    it('delegates to deleteNode with store only when no deletionLog', async () => {
+      vi.mocked(deleteNodeModule.deleteNode).mockResolvedValue(true);
+
+      const actions = createNodeActions({
+        store: mockStore,
+        owner: 'test-plugin',
+      });
+
+      const result = await actions.deleteNode('test-1');
+
+      expect(deleteNodeModule.deleteNode).toHaveBeenCalledWith('test-1', {
+        store: mockStore,
+      });
+      expect(result).toBe(true);
+    });
+
+    it('includes deletionLog when provided', async () => {
+      vi.mocked(deleteNodeModule.deleteNode).mockResolvedValue(true);
+
+      const actions = createNodeActions({
+        store: mockStore,
+        owner: 'test-plugin',
+        deletionLog: mockDeletionLog,
+      });
+
+      await actions.deleteNode('test-1');
+
+      expect(deleteNodeModule.deleteNode).toHaveBeenCalledWith('test-1', {
+        store: mockStore,
+        deletionLog: mockDeletionLog,
+      });
+    });
+
+    it('passes additional options to deleteNode', async () => {
+      vi.mocked(deleteNodeModule.deleteNode).mockResolvedValue(false);
+
+      const actions = createNodeActions({
+        store: mockStore,
+        owner: 'test-plugin',
+        deletionLog: mockDeletionLog,
+      });
+
+      const result = await actions.deleteNode('test-1', { cascade: true });
+
+      expect(deleteNodeModule.deleteNode).toHaveBeenCalledWith('test-1', {
+        store: mockStore,
+        deletionLog: mockDeletionLog,
+        cascade: true,
+      });
+      expect(result).toBe(false);
+    });
+  });
+
+  describe('extendNode', () => {
+    it('delegates to extendNode with store', async () => {
+      const mockNode = {
+        id: 'test-1',
+        internal: { type: 'TestType' },
+        extra: 'data',
+      };
+      vi.mocked(extendNodeModule.extendNode).mockResolvedValue(
+        mockNode as never
+      );
+
+      const actions = createNodeActions({
+        store: mockStore,
+        owner: 'test-plugin',
+      });
+
+      const data = { extra: 'data' };
+      const result = await actions.extendNode('test-1', data);
+
+      expect(extendNodeModule.extendNode).toHaveBeenCalledWith('test-1', data, {
+        store: mockStore,
+      });
+      expect(result).toBe(mockNode);
+    });
+
+    it('passes additional options to extendNode', async () => {
+      const mockNode = { id: 'test-1', internal: { type: 'TestType' } };
+      vi.mocked(extendNodeModule.extendNode).mockResolvedValue(
+        mockNode as never
+      );
+
+      const actions = createNodeActions({
+        store: mockStore,
+        owner: 'test-plugin',
+      });
+
+      const data = { extra: 'data' };
+      await actions.extendNode('test-1', data, { schema: {} } as never);
+
+      expect(extendNodeModule.extendNode).toHaveBeenCalledWith('test-1', data, {
+        store: mockStore,
+        schema: {},
+      });
+    });
+  });
+
+  describe('getNode', () => {
+    it('delegates to getNode with store', () => {
+      const mockNode = { id: 'test-1', internal: { type: 'TestType' } };
+      vi.mocked(queriesModule.getNode).mockReturnValue(mockNode as never);
+
+      const actions = createNodeActions({
+        store: mockStore,
+        owner: 'test-plugin',
+      });
+
+      const result = actions.getNode('test-1');
+
+      expect(queriesModule.getNode).toHaveBeenCalledWith('test-1', mockStore);
+      expect(result).toBe(mockNode);
+    });
+
+    it('returns undefined when node not found', () => {
+      vi.mocked(queriesModule.getNode).mockReturnValue(undefined);
+
+      const actions = createNodeActions({
+        store: mockStore,
+        owner: 'test-plugin',
+      });
+
+      const result = actions.getNode('non-existent');
+
+      expect(result).toBeUndefined();
+    });
+  });
+
+  describe('getNodes', () => {
+    it('delegates to getNodes with store', () => {
+      const mockNodes = [
+        { id: 'test-1', internal: { type: 'TestType' } },
+        { id: 'test-2', internal: { type: 'TestType' } },
+      ];
+      vi.mocked(queriesModule.getNodes).mockReturnValue(mockNodes as never);
+
+      const actions = createNodeActions({
+        store: mockStore,
+        owner: 'test-plugin',
+      });
+
+      const result = actions.getNodes();
+
+      expect(queriesModule.getNodes).toHaveBeenCalledWith(mockStore, undefined);
+      expect(result).toBe(mockNodes);
+    });
+
+    it('passes predicate to getNodes', () => {
+      const mockNodes = [{ id: 'test-1', internal: { type: 'TestType' } }];
+      vi.mocked(queriesModule.getNodes).mockReturnValue(mockNodes as never);
+
+      const actions = createNodeActions({
+        store: mockStore,
+        owner: 'test-plugin',
+      });
+
+      const predicate = (node: Node) => node.internal.id === 'test-1';
+      const result = actions.getNodes(predicate);
+
+      expect(queriesModule.getNodes).toHaveBeenCalledWith(mockStore, predicate);
+      expect(result).toBe(mockNodes);
+    });
+  });
+
+  describe('getNodesByType', () => {
+    it('delegates to getNodesByType with store', () => {
+      const mockNodes = [{ id: 'test-1', internal: { type: 'TestType' } }];
+      vi.mocked(queriesModule.getNodesByType).mockReturnValue(
+        mockNodes as never
+      );
+
+      const actions = createNodeActions({
+        store: mockStore,
+        owner: 'test-plugin',
+      });
+
+      const result = actions.getNodesByType('TestType');
+
+      expect(queriesModule.getNodesByType).toHaveBeenCalledWith(
+        'TestType',
+        mockStore,
+        undefined
+      );
+      expect(result).toBe(mockNodes);
+    });
+
+    it('passes predicate to getNodesByType', () => {
+      const mockNodes = [{ id: 'test-1', internal: { type: 'TestType' } }];
+      vi.mocked(queriesModule.getNodesByType).mockReturnValue(
+        mockNodes as never
+      );
+
+      const actions = createNodeActions({
+        store: mockStore,
+        owner: 'test-plugin',
+      });
+
+      const predicate = (node: Node) => node.internal.id === 'test-1';
+      const result = actions.getNodesByType('TestType', predicate);
+
+      expect(queriesModule.getNodesByType).toHaveBeenCalledWith(
+        'TestType',
+        mockStore,
+        predicate
+      );
+      expect(result).toBe(mockNodes);
+    });
+  });
+});
diff --git a/packages/core/tests/unit/sync/remote.test.ts b/packages/core/tests/unit/sync/remote.test.ts
new file mode 100644
index 0000000..c8c2709
--- /dev/null
+++ b/packages/core/tests/unit/sync/remote.test.ts
@@ -0,0 +1,330 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import {
+  isRemoteReachable,
+  fetchRemoteNodes,
+  tryConnectRemoteWebSocket,
+  initRemoteSync,
+} from '@/sync/remote.js';
+import type { NodeStore } from '@/nodes/store.js';
+import { UDLWebSocketClient } from '@/websocket/client.js';
+
+// Mock fetch globally
+const mockFetch = vi.fn();
+vi.stubGlobal('fetch', mockFetch);
+
+// Mock UDLWebSocketClient
+vi.mock('@/websocket/client.js', () => ({
+  UDLWebSocketClient: vi.fn(),
+}));
+
+// Mock console.log to avoid noise in tests
+vi.spyOn(console, 'log').mockImplementation(() => {});
+
+describe('remote sync', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  describe('isRemoteReachable', () => {
+    it('returns true when remote server responds with ok status', async () => {
+      mockFetch.mockResolvedValueOnce({ ok: true });
+
+      const result = await isRemoteReachable('http://localhost:4000');
+
+      expect(result).toBe(true);
+      expect(mockFetch).toHaveBeenCalledWith(
+        'http://localhost:4000/health',
+        expect.objectContaining({
+          signal: expect.any(AbortSignal),
+        })
+      );
+    });
+
+    it('returns false when remote server responds with non-ok status', async () => {
+      mockFetch.mockResolvedValueOnce({ ok: false });
+
+      const result = await isRemoteReachable('http://localhost:4000');
+
+      expect(result).toBe(false);
+    });
+
+    it('returns false when fetch throws an error', async () => {
+      mockFetch.mockRejectedValueOnce(new Error('Network error'));
+
+      const result = await isRemoteReachable('http://localhost:4000');
+
+      expect(result).toBe(false);
+    });
+
+    it('returns false when request is aborted', async () => {
+      // Mock fetch to check if signal is passed and simulate abort
+      mockFetch.mockImplementationOnce(
+        (_url: string, _options: { signal: AbortSignal }) => {
+          // Simulate the abort controller being triggered
+          return Promise.reject(new DOMException('Aborted', 'AbortError'));
+        }
+      );
+
+      const result = await isRemoteReachable('http://localhost:4000', 100);
+      expect(result).toBe(false);
+    });
+
+    it('uses custom timeout when provided', async () => {
+      mockFetch.mockResolvedValueOnce({ ok: true });
+
+      await isRemoteReachable('http://localhost:4000', 5000);
+
+      expect(mockFetch).toHaveBeenCalled();
+    });
+
+    it('constructs correct health URL from base URL', async () => {
+      mockFetch.mockResolvedValueOnce({ ok: true });
+
+      await isRemoteReachable('https://example.com:8080');
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        'https://example.com:8080/health',
+        expect.any(Object)
+      );
+    });
+  });
+
+  describe('fetchRemoteNodes', () => {
+    it('fetches nodes from /_sync endpoint and populates store', async () => {
+      const mockNodes = [
+        { id: 'node1', type: 'TestType', data: 'test1' },
+        { id: 'node2', type: 'TestType', data: 'test2' },
+      ];
+
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ updated: mockNodes, deleted: [] }),
+      });
+
+      const mockStore = {
+        set: vi.fn(),
+      } as unknown as NodeStore;
+
+      await fetchRemoteNodes('http://localhost:4000', mockStore);
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        'http://localhost:4000/_sync?since=1970-01-01T00%3A00%3A00Z'
+      );
+      expect(mockStore.set).toHaveBeenCalledTimes(2);
+      expect(mockStore.set).toHaveBeenCalledWith(mockNodes[0]);
+      expect(mockStore.set).toHaveBeenCalledWith(mockNodes[1]);
+    });
+
+    it('throws error when response is not ok', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: false,
+        status: 500,
+        statusText: 'Internal Server Error',
+      });
+
+      const mockStore = {
+        set: vi.fn(),
+      } as unknown as NodeStore;
+
+      await expect(
+        fetchRemoteNodes('http://localhost:4000', mockStore)
+      ).rejects.toThrow(
+        'Failed to fetch from remote UDL: 500 Internal Server Error'
+      );
+    });
+
+    it('handles empty node list', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ updated: [], deleted: [] }),
+      });
+
+      const mockStore = {
+        set: vi.fn(),
+      } as unknown as NodeStore;
+
+      await fetchRemoteNodes('http://localhost:4000', mockStore);
+
+      expect(mockStore.set).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('tryConnectRemoteWebSocket', () => {
+    it('returns WebSocket client when connection succeeds', async () => {
+      const mockConnect = vi.fn().mockResolvedValue(undefined);
+      const mockClientInstance = { connect: mockConnect };
+
+      vi.mocked(UDLWebSocketClient).mockImplementation(
+        () => mockClientInstance as unknown as UDLWebSocketClient
+      );
+
+      const mockStore = {} as NodeStore;
+
+      const result = await tryConnectRemoteWebSocket(
+        'http://localhost:4000',
+        mockStore
+      );
+
+      expect(result).toBe(mockClientInstance);
+      expect(UDLWebSocketClient).toHaveBeenCalledWith({
+        url: 'ws://localhost:4000/ws',
+      });
+      expect(mockConnect).toHaveBeenCalledWith(mockStore);
+    });
+
+    it('returns null when connection fails', async () => {
+      const mockConnect = vi
+        .fn()
+        .mockRejectedValue(new Error('Connection failed'));
+      const mockClientInstance = { connect: mockConnect };
+
+      vi.mocked(UDLWebSocketClient).mockImplementation(
+        () => mockClientInstance as unknown as UDLWebSocketClient
+      );
+
+      const mockStore = {} as NodeStore;
+
+      const result = await tryConnectRemoteWebSocket(
+        'http://localhost:4000',
+        mockStore
+      );
+
+      expect(result).toBeNull();
+    });
+
+    it('converts https URL to wss', async () => {
+      const mockConnect = vi.fn().mockResolvedValue(undefined);
+      const mockClientInstance = { connect: mockConnect };
+
+      vi.mocked(UDLWebSocketClient).mockImplementation(
+        () => mockClientInstance as unknown as UDLWebSocketClient
+      );
+
+      const mockStore = {} as NodeStore;
+
+      await tryConnectRemoteWebSocket('https://example.com', mockStore);
+
+      expect(UDLWebSocketClient).toHaveBeenCalledWith({
+        url: 'wss://example.com/ws',
+      });
+    });
+
+    it('passes additional config options to WebSocket client', async () => {
+      const mockConnect = vi.fn().mockResolvedValue(undefined);
+      const mockClientInstance = { connect: mockConnect };
+
+      vi.mocked(UDLWebSocketClient).mockImplementation(
+        () => mockClientInstance as unknown as UDLWebSocketClient
+      );
+
+      const mockStore = {} as NodeStore;
+      const wsConfig = { reconnectDelayMs: 5000, maxReconnectAttempts: 3 };
+
+      await tryConnectRemoteWebSocket(
+        'http://localhost:4000',
+        mockStore,
+        wsConfig
+      );
+
+      expect(UDLWebSocketClient).toHaveBeenCalledWith({
+        url: 'ws://localhost:4000/ws',
+        reconnectDelayMs: 5000,
+        maxReconnectAttempts: 3,
+      });
+    });
+  });
+
+  describe('initRemoteSync', () => {
+    it('fetches nodes and connects to WebSocket', async () => {
+      // Mock fetchRemoteNodes
+      const mockNodes = [{ id: 'node1', type: 'TestType', data: 'test1' }];
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ updated: mockNodes, deleted: [] }),
+      });
+
+      // Mock WebSocket connection
+      const mockConnect = vi.fn().mockResolvedValue(undefined);
+      const mockClientInstance = { connect: mockConnect };
+      vi.mocked(UDLWebSocketClient).mockImplementation(
+        () => mockClientInstance as unknown as UDLWebSocketClient
+      );
+
+      const mockStore = {
+        set: vi.fn(),
+      } as unknown as NodeStore;
+
+      const result = await initRemoteSync(
+        { url: 'http://localhost:4000' },
+        mockStore
+      );
+
+      expect(mockStore.set).toHaveBeenCalledWith(mockNodes[0]);
+      expect(result).toBe(mockClientInstance);
+    });
+
+    it('returns null when WebSocket connection fails', async () => {
+      // Mock fetchRemoteNodes
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ updated: [], deleted: [] }),
+      });
+
+      // Mock WebSocket connection failure
+      const mockConnect = vi
+        .fn()
+        .mockRejectedValue(new Error('Connection failed'));
+      const mockClientInstance = { connect: mockConnect };
+      vi.mocked(UDLWebSocketClient).mockImplementation(
+        () => mockClientInstance as unknown as UDLWebSocketClient
+      );
+
+      const mockStore = {
+        set: vi.fn(),
+      } as unknown as NodeStore;
+
+      const result = await initRemoteSync(
+        { url: 'http://localhost:4000' },
+        mockStore
+      );
+
+      expect(result).toBeNull();
+    });
+
+    it('passes websocket config to tryConnectRemoteWebSocket', async () => {
+      // Mock fetchRemoteNodes
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ updated: [], deleted: [] }),
+      });
+
+      // Mock WebSocket connection
+      const mockConnect = vi.fn().mockResolvedValue(undefined);
+      const mockClientInstance = { connect: mockConnect };
+      vi.mocked(UDLWebSocketClient).mockImplementation(
+        () => mockClientInstance as unknown as UDLWebSocketClient
+      );
+
+      const mockStore = {
+        set: vi.fn(),
+      } as unknown as NodeStore;
+
+      await initRemoteSync(
+        {
+          url: 'http://localhost:4000',
+          websocket: { reconnectDelayMs: 3000 },
+        },
+        mockStore
+      );
+
+      expect(UDLWebSocketClient).toHaveBeenCalledWith({
+        url: 'ws://localhost:4000/ws',
+        reconnectDelayMs: 3000,
+      });
+    });
+  });
+});
diff --git a/packages/core/tests/unit/webhooks/default-handler.test.ts b/packages/core/tests/unit/webhooks/default-handler.test.ts
index 1d0d763..9e042e0 100644
--- a/packages/core/tests/unit/webhooks/default-handler.test.ts
+++ b/packages/core/tests/unit/webhooks/default-handler.test.ts
@@ -7,6 +7,7 @@ import { NodeStore } from '@/nodes/store.js';
 import { createNodeActions } from '@/nodes/actions/index.js';
 import type { WebhookHandlerContext } from '@/webhooks/types.js';
 import type { ServerResponse } from 'node:http';
+import type { Node } from '@/nodes/types.js';
 
 describe('DEFAULT_WEBHOOK_PATH', () => {
   it('should be "sync"', () => {
@@ -85,8 +86,10 @@ describe('createDefaultWebhookHandler', () => {
       expect(node).toBeDefined();
       expect(node!.internal.type).toBe('Product');
       expect(node!.internal.owner).toBe('test-plugin');
-      expect((node as Record<string, unknown>).title).toBe('Test Product');
-      expect((node as Record<string, unknown>).price).toBe(99);
+      expect((node as unknown as Record<string, unknown>)['title']).toBe(
+        'Test Product'
+      );
+      expect((node as unknown as Record<string, unknown>)['price']).toBe(99);
     });
 
     it('should update an existing node', async () => {
@@ -117,7 +120,9 @@ describe('createDefaultWebhookHandler', () => {
 
       expect(res.getStatusCode()).toBe(200);
       const node = store.get('product-1');
-      expect((node as Record<string, unknown>).title).toBe('Updated');
+      expect((node as unknown as Record<string, unknown>)['title']).toBe(
+        'Updated'
+      );
     });
   });
 
@@ -210,7 +215,9 @@ describe('createDefaultWebhookHandler', () => {
         nodeId: 'item-1',
       });
       const node = store.get('item-1');
-      expect((node as Record<string, unknown>).name).toBe('Updated');
+      expect((node as unknown as Record<string, unknown>)['name']).toBe(
+        'Updated'
+      );
     });
 
     it('should return 404 if node does not exist', async () => {
@@ -493,10 +500,12 @@ describe('createDefaultWebhookHandler', () => {
           type: 'Todo',
           owner: 'test-plugin',
           contentDigest: 'abc',
+          createdAt: Date.now(),
+          modifiedAt: Date.now(),
         },
         externalId: '123', // Stored as string to match webhook lookup
         title: 'Original Title',
-      });
+      } as Node);
 
       // Create handler with idField
       const lookupHandler = createDefaultWebhookHandler('test-plugin', {
@@ -525,7 +534,9 @@ describe('createDefaultWebhookHandler', () => {
 
       // Check that the node was updated
       const node = customStore.get('Todo-123');
-      expect((node as Record<string, unknown>).title).toBe('Updated Title');
+      expect((node as unknown as Record<string, unknown>)['title']).toBe(
+        'Updated Title'
+      );
     });
 
     it('should find nodes by custom field for delete', async () => {
@@ -545,10 +556,12 @@ describe('createDefaultWebhookHandler', () => {
           type: 'Todo',
           owner: 'test-plugin',
           contentDigest: 'xyz',
+          createdAt: Date.now(),
+          modifiedAt: Date.now(),
         },
         externalId: '456',
         title: 'To Delete',
-      });
+      } as Node);
 
       const lookupHandler = createDefaultWebhookHandler('test-plugin', {
         idField: 'externalId',
@@ -618,7 +631,9 @@ describe('createDefaultWebhookHandler', () => {
       // Node should exist with the generated internal ID
       const node = customStore.get(responseBody.internalId);
       expect(node).toBeDefined();
-      expect((node as Record<string, unknown>).name).toBe('New Product');
+      expect((node as unknown as Record<string, unknown>)['name']).toBe(
+        'New Product'
+      );
     });
 
     it('should find nodes when externalId is numeric but nodeId is string', async () => {
@@ -638,10 +653,12 @@ describe('createDefaultWebhookHandler', () => {
           type: 'Todo',
           owner: 'test-plugin',
           contentDigest: 'abc',
+          createdAt: Date.now(),
+          modifiedAt: Date.now(),
         },
         externalId: 42, // Stored as NUMBER
         title: 'Original Title',
-      });
+      } as Node);
 
       const lookupHandler = createDefaultWebhookHandler('test-plugin', {
         idField: 'externalId',
@@ -669,7 +686,9 @@ describe('createDefaultWebhookHandler', () => {
 
       // Check that the node was updated
       const node = customStore.get('Todo-internal-123');
-      expect((node as Record<string, unknown>).title).toBe('Updated Title');
+      expect((node as unknown as Record<string, unknown>)['title']).toBe(
+        'Updated Title'
+      );
     });
 
     it('should upsert existing nodes found by idField', async () => {
@@ -689,10 +708,12 @@ describe('createDefaultWebhookHandler', () => {
           type: 'Item',
           owner: 'test-plugin',
           contentDigest: 'orig',
+          createdAt: Date.now(),
+          modifiedAt: Date.now(),
         },
         itemCode: 'ABC',
         value: 100,
-      });
+      } as Node);
 
       const lookupHandler = createDefaultWebhookHandler('test-plugin', {
         idField: 'itemCode',
@@ -721,7 +742,181 @@ describe('createDefaultWebhookHandler', () => {
 
       // Check that the existing node was updated
       const node = customStore.get('Item-ABC');
-      expect((node as Record<string, unknown>).value).toBe(200);
+      expect((node as unknown as Record<string, unknown>)['value']).toBe(200);
+    });
+
+    it('should fallback to linear scan for nodes not in index with string nodeId', async () => {
+      const customStore = new NodeStore();
+      const actions = createNodeActions({
+        store: customStore,
+        owner: 'test-plugin',
+      });
+
+      // Pre-create a node
+      customStore.set({
+        internal: {
+          id: 'Legacy-123',
+          type: 'Legacy',
+          owner: 'test-plugin',
+          contentDigest: 'legacy',
+          createdAt: Date.now(),
+          modifiedAt: Date.now(),
+        },
+        legacyId: 'legacy-abc', // String value
+        title: 'Legacy Node',
+      } as Node);
+      customStore.registerIndex('Legacy', 'legacyId');
+
+      // Mock getByField to simulate index miss (forces linear scan)
+      const originalGetByField = customStore.getByField.bind(customStore);
+      customStore.getByField = vi.fn().mockReturnValue(undefined);
+
+      const lookupHandler = createDefaultWebhookHandler('test-plugin', {
+        idField: 'legacyId',
+      });
+
+      const res = createMockResponse();
+      await lookupHandler(null as never, res, {
+        store: customStore,
+        actions,
+        rawBody: Buffer.from('{}'),
+        body: {
+          operation: 'update',
+          nodeId: 'legacy-abc', // String lookup
+          nodeType: 'Legacy',
+          data: { legacyId: 'legacy-abc', title: 'Updated Legacy' },
+        },
+      });
+
+      expect(res.getStatusCode()).toBe(200);
+      expect(JSON.parse(res.getBody())).toMatchObject({
+        updated: true,
+        nodeId: 'legacy-abc',
+        internalId: 'Legacy-123',
+      });
+
+      // Restore original
+      customStore.getByField = originalGetByField;
+    });
+
+    it('should fallback to linear scan for nodes not in index with numeric nodeId', async () => {
+      const customStore = new NodeStore();
+      const actions = createNodeActions({
+        store: customStore,
+        owner: 'test-plugin',
+      });
+
+      // Pre-create a node with numeric field value
+      customStore.set({
+        internal: {
+          id: 'Numeric-999',
+          type: 'Numeric',
+          owner: 'test-plugin',
+          contentDigest: 'num',
+          createdAt: Date.now(),
+          modifiedAt: Date.now(),
+        },
+        numId: 999, // Numeric value
+        title: 'Numeric Node',
+      } as Node);
+      customStore.registerIndex('Numeric', 'numId');
+
+      // Mock getByField to simulate index miss (forces linear scan for numeric comparison)
+      customStore.getByField = vi.fn().mockReturnValue(undefined);
+
+      const lookupHandler = createDefaultWebhookHandler('test-plugin', {
+        idField: 'numId',
+      });
+
+      const res = createMockResponse();
+      await lookupHandler(null as never, res, {
+        store: customStore,
+        actions,
+        rawBody: Buffer.from('{}'),
+        body: {
+          operation: 'update',
+          nodeId: '999', // String from JSON that looks numeric
+          nodeType: 'Numeric',
+          data: { numId: 999, title: 'Updated Numeric' },
+        },
+      });
+
+      expect(res.getStatusCode()).toBe(200);
+      expect(JSON.parse(res.getBody())).toMatchObject({
+        updated: true,
+        nodeId: '999',
+        internalId: 'Numeric-999',
+      });
+    });
+  });
+
+  describe('delete failure handling', () => {
+    it('should return 500 if deleteNode fails unexpectedly', async () => {
+      const customStore = new NodeStore();
+      const actions = createNodeActions({
+        store: customStore,
+        owner: 'test-plugin',
+      });
+
+      // Pre-create a node
+      customStore.set({
+        internal: {
+          id: 'fail-delete',
+          type: 'Test',
+          owner: 'test-plugin',
+          contentDigest: 'abc',
+          createdAt: Date.now(),
+          modifiedAt: Date.now(),
+        },
+        title: 'Will fail delete',
+      } as Node);
+
+      // Mock deleteNode to return false (simulating a rare failure)
+      actions.deleteNode = vi.fn().mockResolvedValue(false);
+
+      const testHandler = createDefaultWebhookHandler('test-plugin');
+
+      const res = createMockResponse();
+      await testHandler(null as never, res, {
+        store: customStore,
+        actions,
+        rawBody: Buffer.from('{}'),
+        body: {
+          operation: 'delete',
+          nodeId: 'fail-delete',
+          nodeType: 'Test',
+        },
+      });
+
+      expect(res.getStatusCode()).toBe(500);
+      expect(JSON.parse(res.getBody())).toMatchObject({
+        error: 'Delete failed',
+        nodeId: 'fail-delete',
+        internalId: 'fail-delete',
+      });
+    });
+  });
+
+  describe('error handling', () => {
+    it('should handle non-Error throws gracefully', async () => {
+      const context = createMockContext({
+        operation: 'upsert',
+        nodeId: 'test',
+        nodeType: 'Test',
+        data: { foo: 'bar' },
+      });
+
+      // Mock createNode to throw a non-Error value
+      context.actions.createNode = vi.fn().mockRejectedValue('string error');
+
+      const res = createMockResponse();
+      await handler(null as never, res, context);
+
+      expect(res.getStatusCode()).toBe(500);
+      expect(JSON.parse(res.getBody())).toEqual({
+        error: 'Internal server error',
+        message: 'Unknown error',
+      });
     });
   });
 });
diff --git a/packages/core/tests/unit/webhooks/outbound.test.ts b/packages/core/tests/unit/webhooks/outbound.test.ts
index 3e431b7..66b86e0 100644
--- a/packages/core/tests/unit/webhooks/outbound.test.ts
+++ b/packages/core/tests/unit/webhooks/outbound.test.ts
@@ -702,6 +702,44 @@ describe('OutboundWebhookManager', () => {
       expect(fetchMock).toHaveBeenCalledTimes(3);
     });
 
+    it('should handle non-Error rejection values', async () => {
+      // Reject with a non-Error value (string)
+      fetchMock.mockRejectedValue('string rejection');
+
+      const manager = new OutboundWebhookManager([
+        { url: 'https://example.com/webhook', retries: 0 },
+      ]);
+      const batch = createMockBatch(1);
+
+      const results = await manager.triggerAll(batch);
+
+      expect(results[0]!.success).toBe(false);
+      expect(results[0]!.error).toBe('string rejection');
+      expect(results[0]!.attempts).toBe(1);
+    });
+
+    it('should fallback to Unknown error when error message is undefined', async () => {
+      // Create an error object with undefined message
+      const errorWithNoMessage = new Error();
+      // Force message to undefined (cast required as message is normally a string)
+      Object.defineProperty(errorWithNoMessage, 'message', {
+        value: undefined,
+      });
+
+      fetchMock.mockRejectedValue(errorWithNoMessage);
+
+      const manager = new OutboundWebhookManager([
+        { url: 'https://example.com/webhook', retries: 0 },
+      ]);
+      const batch = createMockBatch(1);
+
+      const results = await manager.triggerAll(batch);
+
+      expect(results[0]!.success).toBe(false);
+      expect(results[0]!.error).toBe('Unknown error');
+      expect(results[0]!.attempts).toBe(1);
+    });
+
     it('should use default retry settings', async () => {
       fetchMock.mockRejectedValue(new Error('Error'));
 
@@ -798,4 +836,48 @@ describe('OutboundWebhookManager', () => {
       expect(manager.getConfigCount()).toBe(3);
     });
   });
+
+  describe('Promise.allSettled rejected handling', () => {
+    it('should handle rejected promise with Error object', async () => {
+      // Create a manager instance
+      const manager = new OutboundWebhookManager([
+        { url: 'https://example.com/webhook', retries: 0 },
+      ]);
+
+      // Access private trigger method and make it reject
+      const triggerError = new Error('Unexpected rejection');
+      vi.spyOn(
+        manager as unknown as { trigger: () => Promise<never> },
+        'trigger' as never
+      ).mockRejectedValueOnce(triggerError);
+
+      const batch = createMockBatch(1);
+      const results = await manager.triggerAll(batch);
+
+      expect(results.length).toBe(1);
+      expect(results[0]!.success).toBe(false);
+      expect(results[0]!.error).toBe('Unexpected rejection');
+      expect(results[0]!.attempts).toBe(0);
+    });
+
+    it('should handle rejected promise with non-Error value', async () => {
+      const manager = new OutboundWebhookManager([
+        { url: 'https://example.com/webhook', retries: 0 },
+      ]);
+
+      // Make trigger reject with a non-Error value (string)
+      vi.spyOn(
+        manager as unknown as { trigger: () => Promise<never> },
+        'trigger' as never
+      ).mockRejectedValueOnce('string error reason');
+
+      const batch = createMockBatch(1);
+      const results = await manager.triggerAll(batch);
+
+      expect(results.length).toBe(1);
+      expect(results[0]!.success).toBe(false);
+      expect(results[0]!.error).toBe('string error reason');
+      expect(results[0]!.attempts).toBe(0);
+    });
+  });
 });
diff --git a/packages/core/tests/unit/webhooks/processor.test.ts b/packages/core/tests/unit/webhooks/processor.test.ts
new file mode 100644
index 0000000..a236414
--- /dev/null
+++ b/packages/core/tests/unit/webhooks/processor.test.ts
@@ -0,0 +1,576 @@
+/**
+ * Tests for Webhook Batch Processor
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { EventEmitter } from 'node:events';
+
+// Mock dependencies before importing the module under test
+vi.mock('@/webhooks/registry.js', () => ({
+  defaultWebhookRegistry: {
+    getHandler: vi.fn(),
+  },
+}));
+
+vi.mock('@/webhooks/queue.js', () => {
+  const mockQueue = new EventEmitter();
+  return {
+    defaultWebhookQueue: mockQueue,
+  };
+});
+
+vi.mock('@/webhooks/hooks.js', () => ({
+  getWebhookHooks: vi.fn(() => ({})),
+}));
+
+vi.mock('@/nodes/defaultStore.js', () => ({
+  defaultStore: {
+    get: vi.fn(),
+    set: vi.fn(),
+  },
+}));
+
+vi.mock('@/nodes/actions/index.js', () => ({
+  createNodeActions: vi.fn(() => ({
+    createNode: vi.fn(),
+    deleteNode: vi.fn(),
+    getNode: vi.fn(),
+  })),
+}));
+
+import {
+  initializeWebhookProcessor,
+  processWebhookBatch,
+} from '@/webhooks/processor.js';
+import { defaultWebhookRegistry } from '@/webhooks/registry.js';
+import { defaultWebhookQueue } from '@/webhooks/queue.js';
+import { getWebhookHooks } from '@/webhooks/hooks.js';
+import { createNodeActions } from '@/nodes/actions/index.js';
+import type { QueuedWebhook } from '@/webhooks/queue.js';
+
+describe('webhooks/processor', () => {
+  const mockConsoleLog = vi.spyOn(console, 'log').mockImplementation(() => {});
+  const mockConsoleWarn = vi
+    .spyOn(console, 'warn')
+    .mockImplementation(() => {});
+  const mockConsoleError = vi
+    .spyOn(console, 'error')
+    .mockImplementation(() => {});
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    // Remove all listeners to start fresh
+    defaultWebhookQueue.removeAllListeners();
+  });
+
+  afterEach(() => {
+    defaultWebhookQueue.removeAllListeners();
+  });
+
+  const createQueuedWebhook = (
+    overrides: Partial<QueuedWebhook> = {}
+  ): QueuedWebhook => ({
+    pluginName: 'test-plugin',
+    rawBody: Buffer.from('{"test": true}'),
+    body: { test: true },
+    headers: { 'content-type': 'application/json' },
+    timestamp: Date.now(),
+    ...overrides,
+  });
+
+  describe('initializeWebhookProcessor', () => {
+    it('should set up event listeners on the queue', () => {
+      initializeWebhookProcessor();
+
+      // Check that listeners are registered
+      expect(defaultWebhookQueue.listenerCount('webhook:process')).toBe(1);
+      expect(defaultWebhookQueue.listenerCount('webhook:batch-complete')).toBe(
+        1
+      );
+      expect(defaultWebhookQueue.listenerCount('webhook:batch-error')).toBe(1);
+      expect(mockConsoleLog).toHaveBeenCalledWith(
+        '🔗 Webhook processor initialized'
+      );
+    });
+
+    it('should process individual webhooks when webhook:process is emitted', async () => {
+      const mockHandler = vi.fn().mockResolvedValue(undefined);
+      vi.mocked(defaultWebhookRegistry.getHandler).mockReturnValue({
+        pluginName: 'test-plugin',
+        handler: mockHandler,
+      });
+
+      initializeWebhookProcessor();
+
+      const webhook = createQueuedWebhook();
+      defaultWebhookQueue.emit('webhook:process', webhook);
+
+      // Wait for async processing
+      await vi.waitFor(() => {
+        expect(mockHandler).toHaveBeenCalled();
+      });
+
+      expect(createNodeActions).toHaveBeenCalledWith({
+        store: expect.anything(),
+        owner: 'test-plugin',
+      });
+    });
+
+    it('should warn if handler is not found for webhook', async () => {
+      vi.mocked(defaultWebhookRegistry.getHandler).mockReturnValue(undefined);
+
+      initializeWebhookProcessor();
+
+      const webhook = createQueuedWebhook({ pluginName: 'unknown-plugin' });
+      defaultWebhookQueue.emit('webhook:process', webhook);
+
+      await vi.waitFor(() => {
+        expect(mockConsoleWarn).toHaveBeenCalledWith(
+          '⚠️ Handler not found for queued webhook: unknown-plugin'
+        );
+      });
+    });
+
+    it('should catch and log handler errors without rethrowing', async () => {
+      const mockHandler = vi
+        .fn()
+        .mockRejectedValue(new Error('Handler failed'));
+      vi.mocked(defaultWebhookRegistry.getHandler).mockReturnValue({
+        pluginName: 'test-plugin',
+        handler: mockHandler,
+      });
+
+      initializeWebhookProcessor();
+
+      const webhook = createQueuedWebhook();
+      defaultWebhookQueue.emit('webhook:process', webhook);
+
+      await vi.waitFor(() => {
+        expect(mockConsoleError).toHaveBeenCalledWith(
+          '❌ Error processing webhook test-plugin:',
+          expect.any(Error)
+        );
+      });
+    });
+
+    it('should run onAfterWebhookTriggered hook on batch complete', async () => {
+      const mockAfterHook = vi.fn().mockResolvedValue(undefined);
+      vi.mocked(getWebhookHooks).mockReturnValue({
+        onAfterWebhookTriggered: mockAfterHook,
+      });
+
+      initializeWebhookProcessor();
+
+      const batch = {
+        webhooks: [createQueuedWebhook()],
+        startedAt: Date.now(),
+        completedAt: Date.now(),
+      };
+
+      defaultWebhookQueue.emit('webhook:batch-complete', batch);
+
+      await vi.waitFor(() => {
+        expect(mockConsoleLog).toHaveBeenCalledWith(
+          '🪝 Running onAfterWebhookTriggered hook...'
+        );
+        expect(mockAfterHook).toHaveBeenCalledWith({
+          batch,
+          store: expect.anything(),
+        });
+      });
+    });
+
+    it('should catch and log onAfterWebhookTriggered hook errors', async () => {
+      const hookError = new Error('After hook failed');
+      const mockAfterHook = vi.fn().mockRejectedValue(hookError);
+      vi.mocked(getWebhookHooks).mockReturnValue({
+        onAfterWebhookTriggered: mockAfterHook,
+      });
+
+      initializeWebhookProcessor();
+
+      const batch = {
+        webhooks: [createQueuedWebhook()],
+        startedAt: Date.now(),
+        completedAt: Date.now(),
+      };
+
+      defaultWebhookQueue.emit('webhook:batch-complete', batch);
+
+      await vi.waitFor(() => {
+        expect(mockConsoleError).toHaveBeenCalledWith(
+          '❌ onAfterWebhookTriggered hook error:',
+          hookError
+        );
+      });
+    });
+
+    it('should skip onAfterWebhookTriggered if hook is not defined', async () => {
+      vi.mocked(getWebhookHooks).mockReturnValue({});
+
+      initializeWebhookProcessor();
+
+      const batch = {
+        webhooks: [createQueuedWebhook()],
+        startedAt: Date.now(),
+        completedAt: Date.now(),
+      };
+
+      defaultWebhookQueue.emit('webhook:batch-complete', batch);
+
+      // Wait a tick to ensure async code would have run
+      await new Promise((resolve) => setTimeout(resolve, 10));
+
+      expect(mockConsoleLog).not.toHaveBeenCalledWith(
+        '🪝 Running onAfterWebhookTriggered hook...'
+      );
+    });
+
+    it('should log batch errors', () => {
+      initializeWebhookProcessor();
+
+      const webhooks = [createQueuedWebhook(), createQueuedWebhook()];
+      const error = new Error('Batch failed');
+
+      defaultWebhookQueue.emit('webhook:batch-error', { webhooks, error });
+
+      expect(mockConsoleError).toHaveBeenCalledWith(
+        '❌ Batch processing failed for 2 webhooks:',
+        error
+      );
+    });
+  });
+
+  describe('processWebhookBatch', () => {
+    it('should process each webhook in the batch', async () => {
+      const mockHandler = vi.fn().mockResolvedValue(undefined);
+      vi.mocked(defaultWebhookRegistry.getHandler).mockReturnValue({
+        pluginName: 'test-plugin',
+        handler: mockHandler,
+      });
+      vi.mocked(getWebhookHooks).mockReturnValue({});
+
+      const webhooks = [
+        createQueuedWebhook({ pluginName: 'plugin-1' }),
+        createQueuedWebhook({ pluginName: 'plugin-2' }),
+      ];
+
+      const batch = await processWebhookBatch(webhooks);
+
+      expect(batch.webhooks).toBe(webhooks);
+      expect(batch.startedAt).toBeLessThanOrEqual(batch.completedAt);
+      expect(mockHandler).toHaveBeenCalledTimes(2);
+    });
+
+    it('should run onBeforeWebhookTriggered hook before processing', async () => {
+      const mockBeforeHook = vi.fn().mockResolvedValue(undefined);
+      const mockHandler = vi.fn().mockResolvedValue(undefined);
+      vi.mocked(getWebhookHooks).mockReturnValue({
+        onBeforeWebhookTriggered: mockBeforeHook,
+      });
+      vi.mocked(defaultWebhookRegistry.getHandler).mockReturnValue({
+        pluginName: 'test-plugin',
+        handler: mockHandler,
+      });
+
+      const webhooks = [createQueuedWebhook()];
+
+      await processWebhookBatch(webhooks);
+
+      expect(mockConsoleLog).toHaveBeenCalledWith(
+        '🪝 Running onBeforeWebhookTriggered hook...'
+      );
+      expect(mockBeforeHook).toHaveBeenCalledWith({
+        batch: expect.objectContaining({ webhooks }),
+        store: expect.anything(),
+      });
+      // Verify hook was called before handler
+      const hookOrder = mockBeforeHook.mock.invocationCallOrder[0];
+      const handlerOrder = mockHandler.mock.invocationCallOrder[0];
+      expect(hookOrder).toBeDefined();
+      expect(handlerOrder).toBeDefined();
+      expect(hookOrder!).toBeLessThan(handlerOrder!);
+    });
+
+    it('should catch and log onBeforeWebhookTriggered hook errors but continue processing', async () => {
+      const hookError = new Error('Before hook failed');
+      const mockBeforeHook = vi.fn().mockRejectedValue(hookError);
+      const mockHandler = vi.fn().mockResolvedValue(undefined);
+      vi.mocked(getWebhookHooks).mockReturnValue({
+        onBeforeWebhookTriggered: mockBeforeHook,
+      });
+      vi.mocked(defaultWebhookRegistry.getHandler).mockReturnValue({
+        pluginName: 'test-plugin',
+        handler: mockHandler,
+      });
+
+      const webhooks = [createQueuedWebhook()];
+
+      const batch = await processWebhookBatch(webhooks);
+
+      expect(mockConsoleError).toHaveBeenCalledWith(
+        '❌ onBeforeWebhookTriggered hook error:',
+        hookError
+      );
+      // Processing should continue despite hook error
+      expect(mockHandler).toHaveBeenCalled();
+      expect(batch.completedAt).toBeGreaterThan(0);
+    });
+
+    it('should skip onBeforeWebhookTriggered if hook is not defined', async () => {
+      vi.mocked(getWebhookHooks).mockReturnValue({});
+      vi.mocked(defaultWebhookRegistry.getHandler).mockReturnValue({
+        pluginName: 'test-plugin',
+        handler: vi.fn().mockResolvedValue(undefined),
+      });
+
+      const webhooks = [createQueuedWebhook()];
+
+      await processWebhookBatch(webhooks);
+
+      expect(mockConsoleLog).not.toHaveBeenCalledWith(
+        '🪝 Running onBeforeWebhookTriggered hook...'
+      );
+    });
+
+    it('should return batch with correct timestamps', async () => {
+      vi.mocked(getWebhookHooks).mockReturnValue({});
+      vi.mocked(defaultWebhookRegistry.getHandler).mockReturnValue(undefined);
+
+      const webhooks = [createQueuedWebhook()];
+      const beforeTime = Date.now();
+
+      const batch = await processWebhookBatch(webhooks);
+
+      expect(batch.startedAt).toBeGreaterThanOrEqual(beforeTime);
+      expect(batch.completedAt).toBeGreaterThanOrEqual(batch.startedAt);
+    });
+
+    it('should handle empty webhook array', async () => {
+      vi.mocked(getWebhookHooks).mockReturnValue({});
+
+      const batch = await processWebhookBatch([]);
+
+      expect(batch.webhooks).toEqual([]);
+      expect(batch.completedAt).toBeGreaterThan(0);
+    });
+  });
+
+  describe('createMockRequest', () => {
+    it('should create a mock request with correct properties', async () => {
+      const mockHandler = vi.fn().mockImplementation((req, _res, _context) => {
+        // Verify mock request properties
+        expect(req.method).toBe('POST');
+        expect(req.url).toBe('/_webhooks/test-plugin/sync');
+        expect(req.headers).toEqual({
+          'content-type': 'application/json',
+          'x-custom': 'header',
+        });
+        expect(req.httpVersion).toBe('1.1');
+        expect(req.httpVersionMajor).toBe(1);
+        expect(req.httpVersionMinor).toBe(1);
+        expect(req.complete).toBe(true);
+        expect(req.aborted).toBe(false);
+        expect(req.rawHeaders).toEqual([]);
+        expect(req.trailers).toEqual({});
+        expect(req.rawTrailers).toEqual([]);
+        return Promise.resolve();
+      });
+
+      vi.mocked(defaultWebhookRegistry.getHandler).mockReturnValue({
+        pluginName: 'test-plugin',
+        handler: mockHandler,
+      });
+      vi.mocked(getWebhookHooks).mockReturnValue({});
+
+      const webhook = createQueuedWebhook({
+        headers: { 'content-type': 'application/json', 'x-custom': 'header' },
+      });
+
+      await processWebhookBatch([webhook]);
+
+      expect(mockHandler).toHaveBeenCalled();
+    });
+
+    it('should have setTimeout and destroy methods on mock request', async () => {
+      const mockHandler = vi.fn().mockImplementation((req, _res, _context) => {
+        expect(typeof req.setTimeout).toBe('function');
+        expect(typeof req.destroy).toBe('function');
+        // Both should return the emitter (self)
+        const result = req.setTimeout();
+        expect(result).toBe(req);
+        const destroyResult = req.destroy();
+        expect(destroyResult).toBe(req);
+        return Promise.resolve();
+      });
+
+      vi.mocked(defaultWebhookRegistry.getHandler).mockReturnValue({
+        pluginName: 'test-plugin',
+        handler: mockHandler,
+      });
+      vi.mocked(getWebhookHooks).mockReturnValue({});
+
+      await processWebhookBatch([createQueuedWebhook()]);
+
+      expect(mockHandler).toHaveBeenCalled();
+    });
+  });
+
+  describe('createMockResponse', () => {
+    it('should create a mock response with correct properties', async () => {
+      const mockHandler = vi.fn().mockImplementation((_req, res, _context) => {
+        // Verify initial mock response properties
+        expect(res.statusCode).toBe(200);
+        expect(res.statusMessage).toBe('OK');
+        expect(res.headersSent).toBe(false);
+        expect(res.writableEnded).toBe(false);
+        return Promise.resolve();
+      });
+
+      vi.mocked(defaultWebhookRegistry.getHandler).mockReturnValue({
+        pluginName: 'test-plugin',
+        handler: mockHandler,
+      });
+      vi.mocked(getWebhookHooks).mockReturnValue({});
+
+      await processWebhookBatch([createQueuedWebhook()]);
+
+      expect(mockHandler).toHaveBeenCalled();
+    });
+
+    it('should track headersSent and writableEnded after writeHead', async () => {
+      const mockHandler = vi.fn().mockImplementation((_req, res, _context) => {
+        expect(res.writableEnded).toBe(false);
+        res.writeHead(200);
+        // After writeHead, headersSent should be true
+        expect(res.writableEnded).toBe(true);
+        return Promise.resolve();
+      });
+
+      vi.mocked(defaultWebhookRegistry.getHandler).mockReturnValue({
+        pluginName: 'test-plugin',
+        handler: mockHandler,
+      });
+      vi.mocked(getWebhookHooks).mockReturnValue({});
+
+      await processWebhookBatch([createQueuedWebhook()]);
+
+      expect(mockHandler).toHaveBeenCalled();
+    });
+
+    it('should track headersSent after end', async () => {
+      const mockHandler = vi.fn().mockImplementation((_req, res, _context) => {
+        expect(res.writableEnded).toBe(false);
+        res.end();
+        expect(res.writableEnded).toBe(true);
+        return Promise.resolve();
+      });
+
+      vi.mocked(defaultWebhookRegistry.getHandler).mockReturnValue({
+        pluginName: 'test-plugin',
+        handler: mockHandler,
+      });
+      vi.mocked(getWebhookHooks).mockReturnValue({});
+
+      await processWebhookBatch([createQueuedWebhook()]);
+
+      expect(mockHandler).toHaveBeenCalled();
+    });
+
+    it('should have all required response methods', async () => {
+      const mockHandler = vi.fn().mockImplementation((_req, res, _context) => {
+        expect(typeof res.writeHead).toBe('function');
+        expect(typeof res.setHeader).toBe('function');
+        expect(typeof res.getHeader).toBe('function');
+        expect(typeof res.removeHeader).toBe('function');
+        expect(typeof res.write).toBe('function');
+        expect(typeof res.end).toBe('function');
+        expect(typeof res.flushHeaders).toBe('function');
+        expect(typeof res.addTrailers).toBe('function');
+        expect(typeof res.setTimeout).toBe('function');
+        expect(typeof res.destroy).toBe('function');
+        expect(typeof res.cork).toBe('function');
+        expect(typeof res.uncork).toBe('function');
+        expect(typeof res.assignSocket).toBe('function');
+        expect(typeof res.detachSocket).toBe('function');
+        expect(typeof res.writeContinue).toBe('function');
+        expect(typeof res.writeEarlyHints).toBe('function');
+        expect(typeof res.writeProcessing).toBe('function');
+
+        // Test return values
+        expect(res.setHeader()).toBe(res);
+        expect(res.getHeader()).toBeUndefined();
+        expect(res.removeHeader()).toBeUndefined();
+        expect(res.write()).toBe(true);
+        expect(res.flushHeaders()).toBeUndefined();
+        expect(res.addTrailers()).toBeUndefined();
+        expect(res.setTimeout()).toBe(res);
+        expect(res.destroy()).toBe(res);
+        expect(res.cork()).toBeUndefined();
+        expect(res.uncork()).toBeUndefined();
+        expect(res.assignSocket()).toBeUndefined();
+        expect(res.detachSocket()).toBeUndefined();
+        expect(res.writeContinue()).toBeUndefined();
+        expect(res.writeEarlyHints()).toBeUndefined();
+        expect(res.writeProcessing()).toBeUndefined();
+
+        return Promise.resolve();
+      });
+
+      vi.mocked(defaultWebhookRegistry.getHandler).mockReturnValue({
+        pluginName: 'test-plugin',
+        handler: mockHandler,
+      });
+      vi.mocked(getWebhookHooks).mockReturnValue({});
+
+      await processWebhookBatch([createQueuedWebhook()]);
+
+      expect(mockHandler).toHaveBeenCalled();
+    });
+
+    it('should return this from writeHead', async () => {
+      const mockHandler = vi.fn().mockImplementation((_req, res, _context) => {
+        const result = res.writeHead(200, { 'Content-Type': 'text/plain' });
+        expect(result).toBe(res);
+        return Promise.resolve();
+      });
+
+      vi.mocked(defaultWebhookRegistry.getHandler).mockReturnValue({
+        pluginName: 'test-plugin',
+        handler: mockHandler,
+      });
+      vi.mocked(getWebhookHooks).mockReturnValue({});
+
+      await processWebhookBatch([createQueuedWebhook()]);
+
+      expect(mockHandler).toHaveBeenCalled();
+    });
+  });
+
+  describe('processWebhook context', () => {
+    it('should pass correct context to handler', async () => {
+      const mockHandler = vi.fn().mockImplementation((_req, _res, context) => {
+        expect(context.store).toBeDefined();
+        expect(context.actions).toBeDefined();
+        expect(context.rawBody).toBeInstanceOf(Buffer);
+        expect(context.body).toEqual({ test: true });
+        return Promise.resolve();
+      });
+
+      vi.mocked(defaultWebhookRegistry.getHandler).mockReturnValue({
+        pluginName: 'test-plugin',
+        handler: mockHandler,
+      });
+      vi.mocked(getWebhookHooks).mockReturnValue({});
+
+      const webhook = createQueuedWebhook({
+        rawBody: Buffer.from('{"test": true}'),
+        body: { test: true },
+      });
+
+      await processWebhookBatch([webhook]);
+
+      expect(mockHandler).toHaveBeenCalled();
+    });
+  });
+});
diff --git a/packages/core/tests/unit/webhooks/queue.test.ts b/packages/core/tests/unit/webhooks/queue.test.ts
index 5d03003..0f213c9 100644
--- a/packages/core/tests/unit/webhooks/queue.test.ts
+++ b/packages/core/tests/unit/webhooks/queue.test.ts
@@ -405,5 +405,31 @@ describe('WebhookQueue', () => {
 
       expect(queue.processing()).toBe(false);
     });
+
+    it('should convert non-Error thrown values to Error', async () => {
+      let receivedError:
+        | { webhooks: QueuedWebhook[]; error: Error }
+        | undefined;
+
+      vi.spyOn(console, 'error').mockImplementation(() => {});
+
+      queue.setBatchProcessor(async () => {
+        throw 'string error message';
+      });
+
+      queue.on(
+        'webhook:batch-error',
+        (error: { webhooks: QueuedWebhook[]; error: Error }) => {
+          receivedError = error;
+        }
+      );
+
+      queue.enqueue(createMockWebhook('plugin', 'path-1'));
+      await queue.flush();
+
+      expect(receivedError).toBeDefined();
+      expect(receivedError?.error).toBeInstanceOf(Error);
+      expect(receivedError?.error.message).toBe('string error message');
+    });
   });
 });
diff --git a/packages/core/tests/unit/websocket/client.test.ts b/packages/core/tests/unit/websocket/client.test.ts
new file mode 100644
index 0000000..7796203
--- /dev/null
+++ b/packages/core/tests/unit/websocket/client.test.ts
@@ -0,0 +1,709 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import WebSocket from 'ws';
+import { UDLWebSocketClient } from '@/websocket/client.js';
+import type { NodeStore } from '@/nodes/store.js';
+
+// WebSocket ready state constants
+const WS_OPEN = 1;
+const WS_CLOSED = 3;
+
+// Mock the ws module
+vi.mock('ws', () => {
+  const MockWebSocket = vi.fn() as ReturnType<typeof vi.fn> & {
+    OPEN: number;
+    CLOSED: number;
+  };
+  MockWebSocket.OPEN = 1;
+  MockWebSocket.CLOSED = 3;
+  return {
+    default: MockWebSocket,
+  };
+});
+
+// Helper to create a mock WebSocket instance
+function createMockWs() {
+  const handlers: Record<string, ((...args: unknown[]) => void)[]> = {};
+  return {
+    on: vi.fn((event: string, handler: (...args: unknown[]) => void) => {
+      if (!handlers[event]) handlers[event] = [];
+      handlers[event].push(handler);
+    }),
+    send: vi.fn(),
+    close: vi.fn(),
+    readyState: WS_OPEN as number,
+    emit: (event: string, ...args: unknown[]) => {
+      handlers[event]?.forEach((h) => h(...args));
+    },
+    handlers,
+  };
+}
+
+// Helper to create a mock store
+function createMockStore(): NodeStore {
+  return {
+    set: vi.fn(),
+    get: vi.fn(),
+    delete: vi.fn(),
+    getByType: vi.fn(),
+    getAll: vi.fn(),
+    clear: vi.fn(),
+    size: 0,
+    types: vi.fn().mockReturnValue([]),
+    onChange: vi.fn(),
+  } as unknown as NodeStore;
+}
+
+describe('UDLWebSocketClient', () => {
+  let mockWs: ReturnType<typeof createMockWs>;
+  let consoleLogSpy: ReturnType<typeof vi.spyOn>;
+  let consoleErrorSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    mockWs = createMockWs();
+    (WebSocket as unknown as ReturnType<typeof vi.fn>).mockImplementation(
+      () => mockWs
+    );
+    consoleLogSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.useRealTimers();
+  });
+
+  describe('constructor', () => {
+    it('should set default config values', () => {
+      const client = new UDLWebSocketClient({ url: 'ws://localhost:4000/ws' });
+      // Access private config for testing - we verify behavior through other tests
+      expect(client).toBeDefined();
+    });
+
+    it('should accept custom config values', () => {
+      const client = new UDLWebSocketClient({
+        url: 'ws://localhost:4000/ws',
+        reconnectDelayMs: 1000,
+        maxReconnectAttempts: 3,
+        pingIntervalMs: 10000,
+      });
+      expect(client).toBeDefined();
+    });
+  });
+
+  describe('connect', () => {
+    it('should create a WebSocket connection and resolve on open', async () => {
+      const client = new UDLWebSocketClient({ url: 'ws://localhost:4000/ws' });
+      const store = createMockStore();
+
+      const connectPromise = client.connect(store);
+
+      // Trigger open event
+      mockWs.emit('open');
+
+      await connectPromise;
+
+      expect(WebSocket).toHaveBeenCalledWith('ws://localhost:4000/ws');
+      expect(mockWs.send).toHaveBeenCalledWith(
+        JSON.stringify({ type: 'subscribe', data: '*' })
+      );
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        '🔌 Connected to remote UDL: ws://localhost:4000/ws'
+      );
+    });
+
+    it('should reject on initial connection error', async () => {
+      const client = new UDLWebSocketClient({ url: 'ws://localhost:4000/ws' });
+      const store = createMockStore();
+
+      const connectPromise = client.connect(store);
+
+      // Trigger error event
+      const error = new Error('Connection refused');
+      mockWs.emit('error', error);
+
+      await expect(connectPromise).rejects.toThrow('Connection refused');
+      expect(consoleErrorSpy).toHaveBeenCalledWith(
+        '🔌 WebSocket error:',
+        'Connection refused'
+      );
+    });
+
+    it('should reject when WebSocket constructor throws', async () => {
+      (WebSocket as unknown as ReturnType<typeof vi.fn>).mockImplementation(
+        () => {
+          throw new Error('WebSocket not supported');
+        }
+      );
+
+      const client = new UDLWebSocketClient({ url: 'ws://localhost:4000/ws' });
+      const store = createMockStore();
+
+      await expect(client.connect(store)).rejects.toThrow(
+        'WebSocket not supported'
+      );
+    });
+  });
+
+  describe('message handling', () => {
+    it('should handle connected message', async () => {
+      const client = new UDLWebSocketClient({ url: 'ws://localhost:4000/ws' });
+      const store = createMockStore();
+
+      const connectPromise = client.connect(store);
+      mockWs.emit('open');
+      await connectPromise;
+
+      const message = {
+        type: 'connected',
+        data: { message: 'Welcome to UDL' },
+      };
+      mockWs.emit('message', Buffer.from(JSON.stringify(message)));
+
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        '🔌 Remote UDL:',
+        'Welcome to UDL'
+      );
+    });
+
+    it('should handle subscribed message', async () => {
+      const client = new UDLWebSocketClient({ url: 'ws://localhost:4000/ws' });
+      const store = createMockStore();
+
+      const connectPromise = client.connect(store);
+      mockWs.emit('open');
+      await connectPromise;
+
+      const message = {
+        type: 'subscribed',
+        data: { types: ['Product', 'Category'] },
+      };
+      mockWs.emit('message', Buffer.from(JSON.stringify(message)));
+
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        '🔌 Subscribed to node types:',
+        ['Product', 'Category']
+      );
+    });
+
+    it('should handle pong message silently', async () => {
+      const client = new UDLWebSocketClient({ url: 'ws://localhost:4000/ws' });
+      const store = createMockStore();
+
+      const connectPromise = client.connect(store);
+      mockWs.emit('open');
+      await connectPromise;
+
+      consoleLogSpy.mockClear();
+
+      const message = { type: 'pong' };
+      mockWs.emit('message', Buffer.from(JSON.stringify(message)));
+
+      // pong should not log anything
+      expect(consoleLogSpy).not.toHaveBeenCalled();
+    });
+
+    it('should handle node:created message', async () => {
+      const client = new UDLWebSocketClient({ url: 'ws://localhost:4000/ws' });
+      const store = createMockStore();
+
+      const connectPromise = client.connect(store);
+      mockWs.emit('open');
+      await connectPromise;
+
+      const message = {
+        type: 'node:created',
+        nodeId: 'prod-1',
+        nodeType: 'Product',
+        data: { id: 'prod-1', name: 'Test Product' },
+      };
+      mockWs.emit('message', Buffer.from(JSON.stringify(message)));
+
+      expect(store.set).toHaveBeenCalledWith({
+        id: 'prod-1',
+        name: 'Test Product',
+        internal: { id: 'prod-1', type: 'Product' },
+      });
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        '🔄 Remote node:created: Product:prod-1'
+      );
+    });
+
+    it('should handle node:updated message', async () => {
+      const client = new UDLWebSocketClient({ url: 'ws://localhost:4000/ws' });
+      const store = createMockStore();
+
+      const connectPromise = client.connect(store);
+      mockWs.emit('open');
+      await connectPromise;
+
+      const message = {
+        type: 'node:updated',
+        nodeId: 'prod-1',
+        nodeType: 'Product',
+        data: { id: 'prod-1', name: 'Updated Product' },
+      };
+      mockWs.emit('message', Buffer.from(JSON.stringify(message)));
+
+      expect(store.set).toHaveBeenCalledWith({
+        id: 'prod-1',
+        name: 'Updated Product',
+        internal: { id: 'prod-1', type: 'Product' },
+      });
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        '🔄 Remote node:updated: Product:prod-1'
+      );
+    });
+
+    it('should preserve existing internal field on node update', async () => {
+      const client = new UDLWebSocketClient({ url: 'ws://localhost:4000/ws' });
+      const store = createMockStore();
+
+      const connectPromise = client.connect(store);
+      mockWs.emit('open');
+      await connectPromise;
+
+      const message = {
+        type: 'node:created',
+        nodeId: 'prod-1',
+        nodeType: 'Product',
+        data: {
+          id: 'prod-1',
+          name: 'Test Product',
+          internal: { id: 'prod-1', type: 'Product', extra: 'data' },
+        },
+      };
+      mockWs.emit('message', Buffer.from(JSON.stringify(message)));
+
+      expect(store.set).toHaveBeenCalledWith({
+        id: 'prod-1',
+        name: 'Test Product',
+        internal: { id: 'prod-1', type: 'Product', extra: 'data' },
+      });
+    });
+
+    it('should handle node:deleted message', async () => {
+      const client = new UDLWebSocketClient({ url: 'ws://localhost:4000/ws' });
+      const store = createMockStore();
+
+      const connectPromise = client.connect(store);
+      mockWs.emit('open');
+      await connectPromise;
+
+      const message = {
+        type: 'node:deleted',
+        nodeId: 'prod-1',
+        nodeType: 'Product',
+      };
+      mockWs.emit('message', Buffer.from(JSON.stringify(message)));
+
+      expect(store.delete).toHaveBeenCalledWith('prod-1');
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        '🔄 Remote node:deleted: Product:prod-1'
+      );
+    });
+
+    it('should ignore invalid JSON messages', async () => {
+      const client = new UDLWebSocketClient({ url: 'ws://localhost:4000/ws' });
+      const store = createMockStore();
+
+      const connectPromise = client.connect(store);
+      mockWs.emit('open');
+      await connectPromise;
+
+      consoleLogSpy.mockClear();
+
+      // Send invalid JSON
+      mockWs.emit('message', Buffer.from('not valid json'));
+
+      // Should not throw and should not call store methods
+      expect(store.set).not.toHaveBeenCalled();
+      expect(store.delete).not.toHaveBeenCalled();
+    });
+
+    it('should not update store when data is missing on node:created', async () => {
+      const client = new UDLWebSocketClient({ url: 'ws://localhost:4000/ws' });
+      const store = createMockStore();
+
+      const connectPromise = client.connect(store);
+      mockWs.emit('open');
+      await connectPromise;
+
+      const message = {
+        type: 'node:created',
+        nodeId: 'prod-1',
+        nodeType: 'Product',
+        // data is missing
+      };
+      mockWs.emit('message', Buffer.from(JSON.stringify(message)));
+
+      expect(store.set).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('connection close and reconnect', () => {
+    it('should attempt reconnect on connection close', async () => {
+      const client = new UDLWebSocketClient({
+        url: 'ws://localhost:4000/ws',
+        reconnectDelayMs: 1000,
+      });
+      const store = createMockStore();
+
+      const connectPromise = client.connect(store);
+      mockWs.emit('open');
+      await connectPromise;
+
+      // Simulate connection close
+      mockWs.emit('close');
+
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        '🔌 Connection closed, attempting reconnect...'
+      );
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        '🔌 Reconnecting in 1000ms (attempt 1)'
+      );
+
+      // Fast-forward time to trigger reconnect
+      vi.advanceTimersByTime(1000);
+
+      // Should create a new WebSocket
+      expect(WebSocket).toHaveBeenCalledTimes(2);
+    });
+
+    it('should not reconnect if client is closing', async () => {
+      const client = new UDLWebSocketClient({
+        url: 'ws://localhost:4000/ws',
+        reconnectDelayMs: 1000,
+      });
+      const store = createMockStore();
+
+      const connectPromise = client.connect(store);
+      mockWs.emit('open');
+      await connectPromise;
+
+      // Close the client
+      client.close();
+
+      // Reset mock to track new calls
+      (WebSocket as unknown as ReturnType<typeof vi.fn>).mockClear();
+
+      // Simulate connection close (should not reconnect)
+      mockWs.emit('close');
+
+      vi.advanceTimersByTime(5000);
+
+      // Should not create a new WebSocket
+      expect(WebSocket).not.toHaveBeenCalled();
+    });
+
+    it('should stop reconnecting after max attempts', async () => {
+      const client = new UDLWebSocketClient({
+        url: 'ws://localhost:4000/ws',
+        reconnectDelayMs: 100,
+        maxReconnectAttempts: 2,
+      });
+      const store = createMockStore();
+
+      const connectPromise = client.connect(store);
+      mockWs.emit('open');
+      await connectPromise;
+
+      // First close
+      mockWs.emit('close');
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        '🔌 Reconnecting in 100ms (attempt 1)'
+      );
+
+      // Create new mock for reconnect
+      const mockWs2 = createMockWs();
+      (WebSocket as unknown as ReturnType<typeof vi.fn>).mockImplementation(
+        () => mockWs2
+      );
+
+      vi.advanceTimersByTime(100);
+
+      // Second close
+      mockWs2.emit('close');
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        '🔌 Reconnecting in 100ms (attempt 2)'
+      );
+
+      // Create new mock for second reconnect
+      const mockWs3 = createMockWs();
+      (WebSocket as unknown as ReturnType<typeof vi.fn>).mockImplementation(
+        () => mockWs3
+      );
+
+      vi.advanceTimersByTime(100);
+
+      // Third close - should hit max attempts
+      mockWs3.emit('close');
+      expect(consoleErrorSpy).toHaveBeenCalledWith(
+        '🔌 Max reconnect attempts reached, giving up'
+      );
+    });
+
+    it('should not call onError on subsequent connection errors', async () => {
+      const client = new UDLWebSocketClient({
+        url: 'ws://localhost:4000/ws',
+        reconnectDelayMs: 100,
+        maxReconnectAttempts: 5,
+      });
+      const store = createMockStore();
+
+      const connectPromise = client.connect(store);
+      mockWs.emit('open');
+      await connectPromise;
+
+      // Simulate connection close to trigger reconnect
+      mockWs.emit('close');
+
+      // Create new mock for reconnect
+      const mockWs2 = createMockWs();
+      (WebSocket as unknown as ReturnType<typeof vi.fn>).mockImplementation(
+        () => mockWs2
+      );
+
+      vi.advanceTimersByTime(100);
+
+      // Error on reconnect attempt - should not reject (reconnectAttempts > 0)
+      const error = new Error('Reconnect failed');
+      mockWs2.emit('error', error);
+
+      // Should log but not throw
+      expect(consoleErrorSpy).toHaveBeenCalledWith(
+        '🔌 WebSocket error:',
+        'Reconnect failed'
+      );
+    });
+  });
+
+  describe('ping interval', () => {
+    it('should send ping at configured interval', async () => {
+      const client = new UDLWebSocketClient({
+        url: 'ws://localhost:4000/ws',
+        pingIntervalMs: 1000,
+      });
+      const store = createMockStore();
+
+      const connectPromise = client.connect(store);
+      mockWs.emit('open');
+      await connectPromise;
+
+      // Clear previous send calls (subscribe)
+      mockWs.send.mockClear();
+
+      // Advance time to trigger ping
+      vi.advanceTimersByTime(1000);
+
+      expect(mockWs.send).toHaveBeenCalledWith(
+        JSON.stringify({ type: 'ping' })
+      );
+
+      // Another ping
+      vi.advanceTimersByTime(1000);
+      expect(mockWs.send).toHaveBeenCalledTimes(2);
+    });
+
+    it('should stop ping interval on close', async () => {
+      const client = new UDLWebSocketClient({
+        url: 'ws://localhost:4000/ws',
+        pingIntervalMs: 1000,
+      });
+      const store = createMockStore();
+
+      const connectPromise = client.connect(store);
+      mockWs.emit('open');
+      await connectPromise;
+
+      mockWs.send.mockClear();
+
+      // Close the client
+      client.close();
+
+      // Advance time - should not send ping
+      vi.advanceTimersByTime(2000);
+
+      expect(mockWs.send).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('send', () => {
+    it('should not send when WebSocket is not open', async () => {
+      const client = new UDLWebSocketClient({ url: 'ws://localhost:4000/ws' });
+      const store = createMockStore();
+
+      const connectPromise = client.connect(store);
+      mockWs.emit('open');
+      await connectPromise;
+
+      // Set WebSocket to closed state
+      mockWs.readyState = WS_CLOSED;
+      mockWs.send.mockClear();
+
+      // Try to trigger a send via ping
+      vi.advanceTimersByTime(30000);
+
+      expect(mockWs.send).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('close', () => {
+    it('should close WebSocket and clear all timers', async () => {
+      const client = new UDLWebSocketClient({
+        url: 'ws://localhost:4000/ws',
+        reconnectDelayMs: 1000,
+      });
+      const store = createMockStore();
+
+      const connectPromise = client.connect(store);
+      mockWs.emit('open');
+      await connectPromise;
+
+      client.close();
+
+      expect(mockWs.close).toHaveBeenCalled();
+      expect(consoleLogSpy).toHaveBeenCalledWith('🔌 WebSocket client closed');
+    });
+
+    it('should clear reconnect timeout if pending', async () => {
+      const client = new UDLWebSocketClient({
+        url: 'ws://localhost:4000/ws',
+        reconnectDelayMs: 5000,
+      });
+      const store = createMockStore();
+
+      const connectPromise = client.connect(store);
+      mockWs.emit('open');
+      await connectPromise;
+
+      // Trigger close to schedule reconnect
+      mockWs.emit('close');
+
+      // Reset mock before calling client.close()
+      (WebSocket as unknown as ReturnType<typeof vi.fn>).mockClear();
+
+      // Close client before reconnect timer fires
+      client.close();
+
+      // Advance past reconnect delay
+      vi.advanceTimersByTime(10000);
+
+      // Should not have created a new WebSocket
+      expect(WebSocket).not.toHaveBeenCalled();
+    });
+
+    it('should handle close when ws is null', () => {
+      const client = new UDLWebSocketClient({ url: 'ws://localhost:4000/ws' });
+
+      // Close without ever connecting
+      client.close();
+
+      expect(consoleLogSpy).toHaveBeenCalledWith('🔌 WebSocket client closed');
+    });
+  });
+
+  describe('isConnected', () => {
+    it('should return true when WebSocket is open', async () => {
+      const client = new UDLWebSocketClient({ url: 'ws://localhost:4000/ws' });
+      const store = createMockStore();
+
+      const connectPromise = client.connect(store);
+      mockWs.emit('open');
+      await connectPromise;
+
+      expect(client.isConnected()).toBe(true);
+    });
+
+    it('should return false when WebSocket is closed', async () => {
+      const client = new UDLWebSocketClient({ url: 'ws://localhost:4000/ws' });
+      const store = createMockStore();
+
+      const connectPromise = client.connect(store);
+      mockWs.emit('open');
+      await connectPromise;
+
+      mockWs.readyState = WS_CLOSED;
+
+      expect(client.isConnected()).toBe(false);
+    });
+
+    it('should return false when not connected', () => {
+      const client = new UDLWebSocketClient({ url: 'ws://localhost:4000/ws' });
+
+      expect(client.isConnected()).toBe(false);
+    });
+  });
+
+  describe('scheduleReconnect when isClosing', () => {
+    it('should not schedule reconnect when isClosing is true (direct call)', async () => {
+      const client = new UDLWebSocketClient({
+        url: 'ws://localhost:4000/ws',
+        reconnectDelayMs: 100,
+      });
+      const store = createMockStore();
+
+      const connectPromise = client.connect(store);
+      mockWs.emit('open');
+      await connectPromise;
+
+      // Set isClosing to true directly to test the early return in scheduleReconnect
+      (client as unknown as { isClosing: boolean }).isClosing = true;
+
+      // Reset mocks
+      (WebSocket as unknown as ReturnType<typeof vi.fn>).mockClear();
+      consoleLogSpy.mockClear();
+
+      // Call scheduleReconnect directly
+      (
+        client as unknown as { scheduleReconnect: () => void }
+      ).scheduleReconnect();
+
+      // Should not log reconnect attempt
+      expect(consoleLogSpy).not.toHaveBeenCalledWith(
+        expect.stringContaining('Reconnecting')
+      );
+
+      // Advance timers - should not reconnect
+      vi.advanceTimersByTime(5000);
+
+      expect(WebSocket).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('handleNodeDelete when store is null', () => {
+    it('should not delete when store is null', async () => {
+      const client = new UDLWebSocketClient({ url: 'ws://localhost:4000/ws' });
+      const store = createMockStore();
+
+      const connectPromise = client.connect(store);
+      mockWs.emit('open');
+      await connectPromise;
+
+      // Set store to null via private access to test the early return branch
+      (client as unknown as { store: NodeStore | null }).store = null;
+
+      const message = {
+        type: 'node:deleted',
+        nodeId: 'prod-1',
+        nodeType: 'Product',
+      };
+      mockWs.emit('message', Buffer.from(JSON.stringify(message)));
+
+      // store.delete should not be called since store is null
+      expect(store.delete).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('stopPingInterval when pingInterval is null', () => {
+    it('should handle stopPingInterval when interval is already null', () => {
+      const client = new UDLWebSocketClient({ url: 'ws://localhost:4000/ws' });
+
+      // Close without connecting - pingInterval is null
+      client.close();
+
+      // Should not throw
+      expect(consoleLogSpy).toHaveBeenCalledWith('🔌 WebSocket client closed');
+    });
+  });
+});
diff --git a/packages/core/tests/unit/websocket/server.test.ts b/packages/core/tests/unit/websocket/server.test.ts
index 7567b27..49d8d73 100644
--- a/packages/core/tests/unit/websocket/server.test.ts
+++ b/packages/core/tests/unit/websocket/server.test.ts
@@ -373,4 +373,235 @@ describe('UDLWebSocketServer', () => {
       client2.close();
     });
   });
+
+  describe('separate port mode', () => {
+    it('creates server on separate port when port is specified', async () => {
+      // Close the existing server first
+      await wsServer.close();
+
+      // Create a new server on a separate port
+      const separatePortServer = new UDLWebSocketServer(httpServer, {
+        port: 0, // Use port 0 to get a random available port
+        path: '/ws',
+      });
+
+      try {
+        // Server should be running - we can't easily get the port but we can close it
+        expect(separatePortServer.getClientCount()).toBe(0);
+      } finally {
+        await separatePortServer.close();
+        // Re-create the original server for cleanup
+        wsServer = new UDLWebSocketServer(httpServer, { path: '/ws' });
+      }
+    });
+  });
+
+  describe('heartbeat and close', () => {
+    it('clears heartbeat interval on close', async () => {
+      // Close will trigger wss 'close' event which clears the interval
+      await wsServer.close();
+
+      // If we get here without hanging, heartbeat cleanup worked
+      expect(true).toBe(true);
+
+      // Re-create server for cleanup
+      wsServer = new UDLWebSocketServer(httpServer, { path: '/ws' });
+    });
+  });
+
+  describe('edge cases', () => {
+    it('passes custom options to WebSocketServer', async () => {
+      await wsServer.close();
+
+      // Create with custom options
+      const customServer = new UDLWebSocketServer(httpServer, {
+        path: '/custom-ws',
+        options: {
+          maxPayload: 1024,
+        },
+      });
+
+      expect(customServer.getClientCount()).toBe(0);
+
+      await customServer.close();
+      wsServer = new UDLWebSocketServer(httpServer, { path: '/ws' });
+    });
+
+    it('uses default values when no config provided', async () => {
+      await wsServer.close();
+
+      // Create with no config (all defaults)
+      const defaultServer = new UDLWebSocketServer(httpServer);
+
+      expect(defaultServer.getClientCount()).toBe(0);
+
+      await defaultServer.close();
+      wsServer = new UDLWebSocketServer(httpServer, { path: '/ws' });
+    });
+  });
+});
+
+// Separate test suite for heartbeat and timing-sensitive tests
+describe('UDLWebSocketServer heartbeat', () => {
+  it('handles pong response to mark connection as alive', async () => {
+    // Create dedicated server with short heartbeat
+    const heartbeatServer = createServer();
+    await new Promise<void>((resolve) => {
+      heartbeatServer.listen(0, () => resolve());
+    });
+    const port =
+      (heartbeatServer.address() as { port: number } | null)?.port ?? 0;
+
+    const wsServer = new UDLWebSocketServer(heartbeatServer, {
+      path: '/ws',
+      heartbeatIntervalMs: 50,
+    });
+
+    try {
+      // Connect a client that will respond to pings (tests line 176 - pong handler)
+      const client = new WebSocket(`ws://localhost:${port}/ws`);
+      const connectedPromise = waitForMessage(client);
+      await waitForOpen(client);
+      await connectedPromise; // connected message
+
+      // Track that pings are being received
+      let pingCount = 0;
+      client.on('ping', () => {
+        pingCount++;
+      });
+
+      // Wait for multiple heartbeat cycles - client auto-responds with pong
+      await new Promise((resolve) => setTimeout(resolve, 150));
+
+      // Should have received at least one ping
+      expect(pingCount).toBeGreaterThanOrEqual(1);
+      // Client should still be connected (pong response marked it alive)
+      expect(client.readyState).toBe(WebSocket.OPEN);
+
+      client.close();
+    } finally {
+      await wsServer.close();
+      await new Promise<void>((resolve) => {
+        heartbeatServer.close(() => resolve());
+      });
+    }
+  }, 10000);
+
+  it('skips clients with non-OPEN readyState during broadcast', async () => {
+    const broadcastServer = createServer();
+    await new Promise<void>((resolve) => {
+      broadcastServer.listen(0, () => resolve());
+    });
+    const port =
+      (broadcastServer.address() as { port: number } | null)?.port ?? 0;
+
+    const wsServer = new UDLWebSocketServer(broadcastServer, {
+      path: '/ws',
+      heartbeatIntervalMs: 60000,
+    });
+
+    try {
+      // Connect client
+      const client = new WebSocket(`ws://localhost:${port}/ws`);
+      const connectedPromise = waitForMessage(client);
+      await waitForOpen(client);
+      await connectedPromise; // connected message
+
+      // Set up a promise to detect close
+      const closePromise = new Promise<void>((resolve) => {
+        client.once('close', () => resolve());
+      });
+
+      // Close client - this puts it in CLOSING state
+      client.close();
+
+      // Immediately emit a node change - client is in CLOSING/CLOSED state
+      emitNodeChange({
+        type: 'node:created',
+        nodeId: 'test-1',
+        nodeType: 'TestNode',
+        node: createMockNode(),
+        timestamp: new Date().toISOString(),
+      });
+
+      await closePromise;
+
+      // If we get here without error, the broadcast correctly skipped non-OPEN client
+      expect(client.readyState).toBe(WebSocket.CLOSED);
+    } finally {
+      await wsServer.close();
+      await new Promise<void>((resolve) => {
+        broadcastServer.close(() => resolve());
+      });
+    }
+  }, 10000);
+
+  it('cleans up heartbeat when wss close event fires', async () => {
+    const closeServer = createServer();
+    await new Promise<void>((resolve) => {
+      closeServer.listen(0, () => resolve());
+    });
+
+    // Create server with heartbeat enabled
+    const wsServer = new UDLWebSocketServer(closeServer, {
+      path: '/ws',
+      heartbeatIntervalMs: 100,
+    });
+
+    // The wss.on('close') handler (lines 150-154) fires when close() is called
+    await wsServer.close();
+
+    // If close() returns without hanging, the interval was cleared properly
+    expect(true).toBe(true);
+
+    await new Promise<void>((resolve) => {
+      closeServer.close(() => resolve());
+    });
+  });
+
+  it('terminates dead connections on heartbeat check', async () => {
+    const termServer = createServer();
+    await new Promise<void>((resolve) => {
+      termServer.listen(0, () => resolve());
+    });
+    const port = (termServer.address() as { port: number } | null)?.port ?? 0;
+
+    // Create server with very short heartbeat
+    const wsServer = new UDLWebSocketServer(termServer, {
+      path: '/ws',
+      heartbeatIntervalMs: 20,
+    });
+
+    try {
+      // Connect client
+      const client = new WebSocket(`ws://localhost:${port}/ws`);
+      const connectedPromise = waitForMessage(client);
+      await waitForOpen(client);
+      await connectedPromise;
+
+      // Mock the pong method to do nothing (prevent auto-pong from working)
+      const origPong = client.pong.bind(client);
+      client.pong = () => {
+        // Don't actually send pong
+      };
+
+      // Wait for multiple heartbeat cycles
+      // The server sends ping, client doesn't respond with pong
+      // First cycle: isAlive = false, ping sent
+      // Second cycle: isAlive still false -> terminate
+      await new Promise((resolve) => setTimeout(resolve, 100));
+
+      // Restore pong for cleanup
+      client.pong = origPong;
+
+      // The ws library auto-pong happens at the protocol level before our mock,
+      // so the connection might still be open. The key is that the heartbeat code ran.
+      // We verified this test exercises the heartbeat interval callback.
+    } finally {
+      await wsServer.close();
+      await new Promise<void>((resolve) => {
+        termServer.close(() => resolve());
+      });
+    }
+  });
 });

From 7651a6f50e57f83eac23a544091e74e6bd2752b0 Mon Sep 17 00:00:00 2001
From: dawidurbanski <hi@dawidurbanski.com>
Date: Tue, 23 Dec 2025 12:29:37 +0100
Subject: [PATCH 33/46] chore: add changesets for cache manager and instant
 webhook relay

---
 .changeset/adapter-nextjs-config-utils.md | 34 ++++++++++++++++++
 .changeset/cache-manager.md               | 38 ++++++++++++++++++++
 .changeset/config-env-var-support.md      | 23 ++++++++++++
 .changeset/instant-webhook-relay.md       | 43 +++++++++++++++++++++++
 4 files changed, 138 insertions(+)
 create mode 100644 .changeset/adapter-nextjs-config-utils.md
 create mode 100644 .changeset/cache-manager.md
 create mode 100644 .changeset/config-env-var-support.md
 create mode 100644 .changeset/instant-webhook-relay.md

diff --git a/.changeset/adapter-nextjs-config-utils.md b/.changeset/adapter-nextjs-config-utils.md
new file mode 100644
index 0000000..e148b3a
--- /dev/null
+++ b/.changeset/adapter-nextjs-config-utils.md
@@ -0,0 +1,34 @@
+---
+'@universal-data-layer/adapter-nextjs': minor
+---
+
+Add config file support and UDL_ENDPOINT injection for Next.js adapter
+
+The adapter commands now read the UDL port from `udl.config.ts` and automatically inject the `UDL_ENDPOINT` environment variable when spawning Next.js processes.
+
+**Features:**
+
+- `dev`, `build`, and `start` commands read port from config file
+- Port priority: CLI option > config file > default (4000)
+- Next.js processes receive `UDL_ENDPOINT` env var automatically
+- Supports `udl.config.ts`, `udl.config.js`, and `udl.config.mjs`
+
+**Benefits:**
+
+- No need to manually set `UDL_ENDPOINT` in environment
+- `udl.query()` client automatically uses the correct endpoint
+- Consistent port configuration between UDL server and Next.js
+
+**Example:**
+
+```typescript
+// udl.config.ts
+export const { config } = defineConfig({
+  port: 5000, // Adapter commands will use this port
+});
+```
+
+```typescript
+// In Next.js code, udl.query() automatically uses the right endpoint
+const result = await udl.query(GetProducts);
+```
diff --git a/.changeset/cache-manager.md b/.changeset/cache-manager.md
new file mode 100644
index 0000000..278b0fa
--- /dev/null
+++ b/.changeset/cache-manager.md
@@ -0,0 +1,38 @@
+---
+'universal-data-layer': minor
+---
+
+Add centralized cache manager for plugin cache coordination
+
+Introduces a `CacheManager` module that provides a central point for coordinating plugin cache updates. This enables webhook handlers and remote sync to persist changes to disk after store modifications.
+
+**Features:**
+
+- `registerPluginCache(pluginName, cache)`: Register a plugin's cache storage
+- `initPluginCache(pluginName, cacheLocation, customCache?)`: Initialize and register a cache
+- `savePluginCache(pluginName, store?)`: Save a specific plugin's nodes to cache
+- `saveAffectedPlugins(affectedPlugins, store?)`: Save caches for multiple plugins
+- `replaceAllCaches(store?)`: Replace all plugin caches (for remote sync)
+- `setStore(store)`: Set the node store reference for cache operations
+
+**Integration:**
+
+- Loader now uses cache manager for plugin cache operations
+- Webhook batch processing automatically saves affected plugin caches
+- Remote sync persists fetched nodes to cache for offline support
+
+**New exports:**
+
+```typescript
+import {
+  setStore,
+  getStore,
+  registerPluginCache,
+  initPluginCache,
+  savePluginCache,
+  saveAffectedPlugins,
+  replaceAllCaches,
+  clearAllCaches,
+  resetCacheManager,
+} from 'universal-data-layer';
+```
diff --git a/.changeset/config-env-var-support.md b/.changeset/config-env-var-support.md
new file mode 100644
index 0000000..eb82783
--- /dev/null
+++ b/.changeset/config-env-var-support.md
@@ -0,0 +1,23 @@
+---
+'universal-data-layer': patch
+---
+
+Add UDL_ENDPOINT environment variable support to config
+
+The `getConfig()` function now checks for the `UDL_ENDPOINT` environment variable when config hasn't been explicitly initialized. This allows the `udl.query()` client to automatically use the correct endpoint in child processes.
+
+**Features:**
+
+- `UDL_ENDPOINT_ENV` constant for the environment variable name
+- `DEFAULT_UDL_PORT` constant (4000) for consistent default port
+- `isConfigInitialized()` to check if config was explicitly set
+- `resetConfig()` for testing isolation
+
+**How it works:**
+
+When `getConfig()` is called and no config was explicitly set via `createConfig()`, it checks for the `UDL_ENDPOINT` environment variable and uses that endpoint if present.
+
+This enables scenarios like:
+
+- Next.js adapter sets `UDL_ENDPOINT` when spawning Next.js
+- `udl.query()` in Next.js code automatically uses the right endpoint
diff --git a/.changeset/instant-webhook-relay.md b/.changeset/instant-webhook-relay.md
new file mode 100644
index 0000000..33439dc
--- /dev/null
+++ b/.changeset/instant-webhook-relay.md
@@ -0,0 +1,43 @@
+---
+'universal-data-layer': minor
+---
+
+Add instant webhook relay for remote sync
+
+Local UDL instances can now receive and process webhooks instantly via WebSocket relay, eliminating the need to wait for batch debounce on the production server.
+
+**How it works:**
+
+1. Production UDL receives a webhook and queues it
+2. Immediately broadcasts `webhook:received` message to WebSocket subscribers
+3. Local UDL instances receive the message and process the webhook locally
+4. Local caches are updated instantly
+
+**Features:**
+
+- New `webhook:queued` event on WebhookQueue for instant relay
+- New `webhook:received` WebSocket message type
+- `broadcastWebhookReceived(webhook)` method on UDLWebSocketServer
+- `onWebhookReceived` callback on WebSocketClient and RemoteSyncConfig
+- Local UDL instances can process relayed webhooks using registered handlers
+- Node change events are skipped when handling webhooks locally (avoids double processing)
+
+**Configuration:**
+
+The instant relay is automatically enabled when using remote sync. Local instances register webhook handlers by loading plugins with `isLocal: true` option.
+
+**Message format:**
+
+```typescript
+interface WebhookReceivedMessage {
+  type: 'webhook:received';
+  pluginName: string;
+  body: unknown;
+  headers: Record<string, string | string[] | undefined>;
+  timestamp: string;
+}
+```
+
+**Exports:**
+
+- `WebhookReceivedEvent`: Event data passed to onWebhookReceived callback

From fb34bf2b39b33ae7b96b43a3d920cc6eef7ce339 Mon Sep 17 00:00:00 2001
From: dawidurbanski <hi@dawidurbanski.com>
Date: Tue, 23 Dec 2025 12:29:48 +0100
Subject: [PATCH 34/46] feat(core): add centralized cache manager for plugin
 coordination

Introduces CacheManager module that provides a central point for
coordinating plugin cache updates. This enables webhook handlers
and remote sync to persist changes to disk after store modifications.

- registerPluginCache/initPluginCache for cache registration
- savePluginCache for saving individual plugin caches
- saveAffectedPlugins for batch webhook processing
- replaceAllCaches for remote sync persistence
---
 packages/core/src/cache/index.ts   |  14 ++
 packages/core/src/cache/manager.ts | 281 +++++++++++++++++++++++++++++
 2 files changed, 295 insertions(+)
 create mode 100644 packages/core/src/cache/manager.ts

diff --git a/packages/core/src/cache/index.ts b/packages/core/src/cache/index.ts
index b4e49a6..18f2aa7 100644
--- a/packages/core/src/cache/index.ts
+++ b/packages/core/src/cache/index.ts
@@ -5,4 +5,18 @@
  */
 
 export { FileCacheStorage } from './file-cache.js';
+export {
+  setStore,
+  getStore,
+  registerPluginCache,
+  initPluginCache,
+  hasPluginCache,
+  getPluginCache,
+  getRegisteredPlugins,
+  savePluginCache,
+  saveAffectedPlugins,
+  replaceAllCaches,
+  clearAllCaches,
+  resetCacheManager,
+} from './manager.js';
 export type { CacheStorage, CachedData, SerializedNode } from './types.js';
diff --git a/packages/core/src/cache/manager.ts b/packages/core/src/cache/manager.ts
new file mode 100644
index 0000000..c521787
--- /dev/null
+++ b/packages/core/src/cache/manager.ts
@@ -0,0 +1,281 @@
+/**
+ * Cache Manager for coordinating plugin cache updates.
+ *
+ * Provides a central point for webhook handlers and remote sync to update
+ * plugin caches after store changes.
+ */
+
+import type { CacheStorage, CachedData } from './types.js';
+import { FileCacheStorage } from './file-cache.js';
+import type { NodeStore } from '../nodes/store.js';
+
+/**
+ * Entry for a registered plugin cache.
+ */
+interface PluginCacheEntry {
+  pluginName: string;
+  cache: CacheStorage;
+}
+
+// Module-level state
+const pluginCaches = new Map<string, PluginCacheEntry>();
+let store: NodeStore | null = null;
+
+/**
+ * Set the node store reference.
+ * This allows cache operations to access the current store state.
+ */
+export function setStore(nodeStore: NodeStore): void {
+  store = nodeStore;
+}
+
+/**
+ * Get the node store reference.
+ */
+export function getStore(): NodeStore | null {
+  return store;
+}
+
+/**
+ * Register a plugin's cache storage.
+ * Called during plugin loading to associate a plugin with its cache.
+ *
+ * @param pluginName - The plugin name (e.g., '@universal-data-layer/plugin-source-contentful')
+ * @param cache - The cache storage instance for this plugin
+ */
+export function registerPluginCache(
+  pluginName: string,
+  cache: CacheStorage
+): void {
+  pluginCaches.set(pluginName, {
+    pluginName,
+    cache,
+  });
+  console.log(`📦 [CacheManager] Registered cache for plugin: ${pluginName}`);
+}
+
+/**
+ * Initialize and register a plugin's cache storage.
+ * This is the preferred way to set up plugin caching - it handles both
+ * custom CacheStorage implementations and the default FileCacheStorage.
+ *
+ * @param pluginName - The plugin name
+ * @param cacheLocation - Directory for cache files (used by FileCacheStorage)
+ * @param customCache - Optional custom CacheStorage from plugin config
+ * @returns The cache storage instance
+ *
+ * @example
+ * ```typescript
+ * // Use default FileCacheStorage
+ * const cache = initPluginCache('my-plugin', '/path/to/cache');
+ *
+ * // Use custom cache from plugin config
+ * const cache = initPluginCache('my-plugin', '/path/to/cache', pluginConfig.cache);
+ * ```
+ */
+export function initPluginCache(
+  pluginName: string,
+  cacheLocation: string,
+  customCache?: CacheStorage
+): CacheStorage {
+  const cache = customCache ?? new FileCacheStorage(cacheLocation);
+  registerPluginCache(pluginName, cache);
+  return cache;
+}
+
+/**
+ * Check if a plugin has a registered cache.
+ */
+export function hasPluginCache(pluginName: string): boolean {
+  return pluginCaches.has(pluginName);
+}
+
+/**
+ * Get a plugin's cache storage.
+ */
+export function getPluginCache(pluginName: string): CacheStorage | undefined {
+  return pluginCaches.get(pluginName)?.cache;
+}
+
+/**
+ * Get all registered plugin names.
+ */
+export function getRegisteredPlugins(): string[] {
+  return Array.from(pluginCaches.keys());
+}
+
+/**
+ * Save a specific plugin's cache from the current store state.
+ * Only saves nodes owned by the specified plugin.
+ *
+ * @param pluginName - The plugin name to save cache for
+ * @param nodeStore - The node store to read from (optional, uses registered store if not provided)
+ */
+export async function savePluginCache(
+  pluginName: string,
+  nodeStore?: NodeStore
+): Promise<boolean> {
+  const effectiveStore = nodeStore ?? store;
+  if (!effectiveStore) {
+    console.warn(
+      `⚠️ [CacheManager] No store available for saving plugin cache: ${pluginName}`
+    );
+    return false;
+  }
+
+  const entry = pluginCaches.get(pluginName);
+  if (!entry) {
+    // Plugin has no registered cache (caching may be disabled)
+    return false;
+  }
+
+  // Get only nodes owned by this plugin
+  const allNodes = effectiveStore.getAll();
+  const pluginNodes = allNodes.filter(
+    (node) => node.internal.owner === pluginName
+  );
+
+  // Get indexes for node types owned by this plugin
+  const pluginNodeTypes = new Set(pluginNodes.map((n) => n.internal.type));
+  const indexes: Record<string, string[]> = {};
+  for (const nodeType of pluginNodeTypes) {
+    const registeredIndexes = effectiveStore.getRegisteredIndexes(nodeType);
+    if (registeredIndexes.length > 0) {
+      indexes[nodeType] = registeredIndexes;
+    }
+  }
+
+  const cacheData: CachedData = {
+    nodes: pluginNodes,
+    indexes,
+    meta: {
+      version: 1,
+      createdAt: Date.now(),
+      updatedAt: Date.now(),
+    },
+  };
+
+  await entry.cache.save(cacheData);
+  console.log(
+    `💾 [CacheManager] Saved ${pluginNodes.length} nodes for plugin: ${pluginName}`
+  );
+
+  return true;
+}
+
+/**
+ * Save caches for all plugins that own any of the affected nodes.
+ * Used after webhook batch processing.
+ *
+ * @param affectedPlugins - Set of plugin names that were affected
+ * @param nodeStore - The node store to read from (optional)
+ */
+export async function saveAffectedPlugins(
+  affectedPlugins: Set<string>,
+  nodeStore?: NodeStore
+): Promise<void> {
+  const savePromises: Promise<boolean>[] = [];
+
+  for (const pluginName of affectedPlugins) {
+    if (hasPluginCache(pluginName)) {
+      savePromises.push(savePluginCache(pluginName, nodeStore));
+    }
+  }
+
+  await Promise.all(savePromises);
+}
+
+/**
+ * Replace all plugin caches with the current store state.
+ * Used after remote sync to persist fetched data locally.
+ *
+ * @param nodeStore - The node store to read from (optional)
+ */
+export async function replaceAllCaches(nodeStore?: NodeStore): Promise<void> {
+  const effectiveStore = nodeStore ?? store;
+  if (!effectiveStore) {
+    console.warn(
+      '⚠️ [CacheManager] No store available for replacing all caches'
+    );
+    return;
+  }
+
+  // Group all nodes by owner
+  const nodesByOwner = new Map<string, typeof allNodes>();
+  const allNodes = effectiveStore.getAll();
+
+  for (const node of allNodes) {
+    const owner = node.internal.owner;
+    if (!nodesByOwner.has(owner)) {
+      nodesByOwner.set(owner, []);
+    }
+    nodesByOwner.get(owner)!.push(node);
+  }
+
+  // Save each plugin's cache
+  const savePromises: Promise<void>[] = [];
+
+  for (const [pluginName, pluginNodes] of nodesByOwner) {
+    const entry = pluginCaches.get(pluginName);
+    if (!entry) {
+      // Plugin has no registered cache, skip
+      continue;
+    }
+
+    // Get indexes for node types owned by this plugin
+    const pluginNodeTypes = new Set(pluginNodes.map((n) => n.internal.type));
+    const indexes: Record<string, string[]> = {};
+    for (const nodeType of pluginNodeTypes) {
+      const registeredIndexes = effectiveStore.getRegisteredIndexes(nodeType);
+      if (registeredIndexes.length > 0) {
+        indexes[nodeType] = registeredIndexes;
+      }
+    }
+
+    const cacheData: CachedData = {
+      nodes: pluginNodes,
+      indexes,
+      meta: {
+        version: 1,
+        createdAt: Date.now(),
+        updatedAt: Date.now(),
+      },
+    };
+
+    savePromises.push(
+      entry.cache.save(cacheData).then(() => {
+        console.log(
+          `💾 [CacheManager] Replaced cache for plugin: ${pluginName} (${pluginNodes.length} nodes)`
+        );
+      })
+    );
+  }
+
+  await Promise.all(savePromises);
+  console.log(
+    `💾 [CacheManager] Replaced all caches (${nodesByOwner.size} plugins)`
+  );
+}
+
+/**
+ * Clear all registered plugin caches.
+ * Useful for testing.
+ */
+export async function clearAllCaches(): Promise<void> {
+  const clearPromises: Promise<void>[] = [];
+
+  for (const entry of pluginCaches.values()) {
+    clearPromises.push(entry.cache.clear());
+  }
+
+  await Promise.all(clearPromises);
+}
+
+/**
+ * Reset the cache manager state.
+ * Useful for testing to ensure isolation between test runs.
+ */
+export function resetCacheManager(): void {
+  pluginCaches.clear();
+  store = null;
+}

From 71e38bc0c406cf856acef5fd890785acc0dbfc25 Mon Sep 17 00:00:00 2001
From: dawidurbanski <hi@dawidurbanski.com>
Date: Tue, 23 Dec 2025 12:30:03 +0100
Subject: [PATCH 35/46] feat(core): add UDL_ENDPOINT environment variable
 support

getConfig() now checks for UDL_ENDPOINT env var when config hasn't
been explicitly initialized. This allows udl.query() client to
automatically use the correct endpoint in child processes.

- Export DEFAULT_UDL_PORT and UDL_ENDPOINT_ENV constants
- Add isConfigInitialized() to check if config was explicitly set
- Add resetConfig() for testing isolation
---
 packages/core/src/config.ts | 53 ++++++++++++++++++++++++++++++++++---
 1 file changed, 50 insertions(+), 3 deletions(-)

diff --git a/packages/core/src/config.ts b/packages/core/src/config.ts
index fffdef2..3ee66be 100644
--- a/packages/core/src/config.ts
+++ b/packages/core/src/config.ts
@@ -5,15 +5,24 @@ export interface Config {
   host?: string;
 }
 
+/** Default port for UDL server */
+export const DEFAULT_UDL_PORT = 4000;
+
+/** Environment variable name for endpoint override */
+export const UDL_ENDPOINT_ENV = 'UDL_ENDPOINT';
+
 let currentConfig: Config = {
   staticPath: '/static/',
-  endpoint: 'http://localhost:4000/graphql',
-  port: 4000,
+  endpoint: `http://localhost:${DEFAULT_UDL_PORT}/graphql`,
+  port: DEFAULT_UDL_PORT,
   host: 'localhost',
 };
 
+/** Tracks whether config was explicitly set via createConfig */
+let configInitialized = false;
+
 export function createConfig(options?: Partial<Config>): Config {
-  const port = options?.port || currentConfig.port || 4000;
+  const port = options?.port || currentConfig.port || DEFAULT_UDL_PORT;
   const host = options?.host || currentConfig.host || 'localhost';
 
   const config: Config = {
@@ -24,11 +33,49 @@ export function createConfig(options?: Partial<Config>): Config {
   };
 
   currentConfig = config;
+  configInitialized = true;
   return config;
 }
 
+/**
+ * Get the current config.
+ * If config hasn't been explicitly set, checks for UDL_ENDPOINT env var.
+ */
 export function getConfig(): Config {
+  // If config was explicitly set, use it
+  if (configInitialized) {
+    return currentConfig;
+  }
+
+  // Check for environment variable override (Node.js only)
+  if (typeof process !== 'undefined' && process.env?.[UDL_ENDPOINT_ENV]) {
+    return {
+      ...currentConfig,
+      endpoint: process.env[UDL_ENDPOINT_ENV],
+    };
+  }
+
   return currentConfig;
 }
 
+/**
+ * Check if config was explicitly initialized via createConfig.
+ */
+export function isConfigInitialized(): boolean {
+  return configInitialized;
+}
+
+/**
+ * Reset config state (primarily for testing).
+ */
+export function resetConfig(): void {
+  currentConfig = {
+    staticPath: '/static/',
+    endpoint: `http://localhost:${DEFAULT_UDL_PORT}/graphql`,
+    port: DEFAULT_UDL_PORT,
+    host: 'localhost',
+  };
+  configInitialized = false;
+}
+
 export default currentConfig;

From 5408c39249c5fc03909c4ec17bfd358c57f6c5cb Mon Sep 17 00:00:00 2001
From: dawidurbanski <hi@dawidurbanski.com>
Date: Tue, 23 Dec 2025 12:30:15 +0100
Subject: [PATCH 36/46] feat(core): add webhook relay support to WebSocket
 client/server

Enable instant webhook relay from production to local UDL instances
via WebSocket, eliminating wait time for batch debounce.

Server:
- Add broadcastWebhookReceived() method
- Add WebhookReceivedMessage type

Client:
- Add onWebhookReceived callback for instant webhook processing
- Handle webhook:received message type
- Skip node events when processing webhooks locally (avoid double processing)
- Save plugin cache after node updates

Export WebhookReceivedEvent interface for callback typing.
---
 packages/core/src/websocket/client.ts | 81 ++++++++++++++++++++++++++-
 packages/core/src/websocket/server.ts | 41 ++++++++++++++
 2 files changed, 120 insertions(+), 2 deletions(-)

diff --git a/packages/core/src/websocket/client.ts b/packages/core/src/websocket/client.ts
index e9b64d4..b4cacbf 100644
--- a/packages/core/src/websocket/client.ts
+++ b/packages/core/src/websocket/client.ts
@@ -1,11 +1,23 @@
 import WebSocket from 'ws';
 import type { NodeStore } from '@/nodes/store.js';
+import { savePluginCache } from '@/cache/manager.js';
 import type {
   ServerMessage,
   NodeChangeMessage,
+  WebhookReceivedMessage,
   ClientMessage,
 } from './server.js';
 
+/**
+ * Webhook received event data passed to the callback.
+ */
+export interface WebhookReceivedEvent {
+  pluginName: string;
+  body: unknown;
+  headers: Record<string, string | string[] | undefined>;
+  timestamp: string;
+}
+
 /**
  * Configuration for the WebSocket client.
  */
@@ -18,6 +30,11 @@ export interface WebSocketClientConfig {
   maxReconnectAttempts?: number;
   /** Ping interval in milliseconds. Default: 30000 */
   pingIntervalMs?: number;
+  /**
+   * Callback invoked immediately when a webhook:received message is received.
+   * This enables instant processing of webhooks without waiting for batch debounce.
+   */
+  onWebhookReceived?: (event: WebhookReceivedEvent) => void | Promise<void>;
 }
 
 /**
@@ -35,13 +52,17 @@ export interface WebSocketClientConfig {
  * ```
  */
 export class UDLWebSocketClient {
-  private config: Required<WebSocketClientConfig>;
+  private config: Required<Omit<WebSocketClientConfig, 'onWebhookReceived'>> & {
+    onWebhookReceived?: WebSocketClientConfig['onWebhookReceived'];
+  };
   private ws: WebSocket | null = null;
   private store: NodeStore | null = null;
   private reconnectAttempts = 0;
   private reconnectTimeout: ReturnType<typeof setTimeout> | null = null;
   private pingInterval: ReturnType<typeof setInterval> | null = null;
   private isClosing = false;
+  /** When true, node events are handled locally via webhook processing */
+  private handlesWebhooksLocally: boolean;
 
   constructor(config: WebSocketClientConfig) {
     this.config = {
@@ -49,7 +70,11 @@ export class UDLWebSocketClient {
       reconnectDelayMs: config.reconnectDelayMs ?? 5000,
       maxReconnectAttempts: config.maxReconnectAttempts ?? Infinity,
       pingIntervalMs: config.pingIntervalMs ?? 30000,
+      onWebhookReceived: config.onWebhookReceived,
     };
+    // When onWebhookReceived is configured, we process webhooks locally
+    // and should skip redundant node:created/updated events from remote
+    this.handlesWebhooksLocally = !!config.onWebhookReceived;
   }
 
   /**
@@ -134,12 +159,21 @@ export class UDLWebSocketClient {
           // Connection is alive
           break;
 
+        case 'webhook:received':
+          this.handleWebhookReceived(message);
+          break;
+
         case 'node:created':
         case 'node:updated':
-          this.handleNodeUpdate(message);
+          // Skip node events when we handle webhooks locally to avoid double processing
+          // The webhook:received handler already creates nodes in the local store
+          if (!this.handlesWebhooksLocally) {
+            this.handleNodeUpdate(message);
+          }
           break;
 
         case 'node:deleted':
+          // Always handle deletions - they may come from sources other than webhooks
           this.handleNodeDelete(message);
           break;
       }
@@ -169,6 +203,12 @@ export class UDLWebSocketClient {
     console.log(
       `🔄 Remote ${message.type}: ${message.nodeType}:${message.nodeId}`
     );
+
+    // Save plugin cache immediately for maximum sync on local UDL
+    const internal = node['internal'] as Record<string, unknown>;
+    if (internal?.['owner'] && typeof internal['owner'] === 'string') {
+      void savePluginCache(internal['owner']);
+    }
   }
 
   /**
@@ -177,10 +217,47 @@ export class UDLWebSocketClient {
   private handleNodeDelete(message: NodeChangeMessage): void {
     if (!this.store) return;
 
+    // Get the node's owner before deleting for cache update
+    const existingNode = this.store.get(message.nodeId);
+    const owner = existingNode?.internal.owner;
+
     this.store.delete(message.nodeId);
     console.log(
       `🔄 Remote node:deleted: ${message.nodeType}:${message.nodeId}`
     );
+
+    // Save plugin cache immediately for maximum sync on local UDL
+    if (owner) {
+      void savePluginCache(owner);
+    }
+  }
+
+  /**
+   * Handle webhook received from remote.
+   * This is called immediately when the remote receives a webhook, before batch processing.
+   */
+  private handleWebhookReceived(message: WebhookReceivedMessage): void {
+    console.log(`📥 Remote webhook:received: ${message.pluginName}`);
+
+    if (this.config.onWebhookReceived) {
+      // Call the callback to process the webhook locally
+      void Promise.resolve(
+        this.config.onWebhookReceived({
+          pluginName: message.pluginName,
+          body: message.body,
+          headers: message.headers,
+          timestamp: message.timestamp,
+        })
+      )
+        .then(() => {
+          // Save plugin cache immediately after webhook is processed
+          // This ensures local UDL has maximum sync with remote
+          return savePluginCache(message.pluginName);
+        })
+        .catch((error) => {
+          console.error('❌ Error processing relayed webhook:', error);
+        });
+    }
   }
 
   /**
diff --git a/packages/core/src/websocket/server.ts b/packages/core/src/websocket/server.ts
index e9c412a..8589531 100644
--- a/packages/core/src/websocket/server.ts
+++ b/packages/core/src/websocket/server.ts
@@ -8,6 +8,7 @@ import type { WebSocketConfig } from '@/loader.js';
  */
 export type ServerMessage =
   | NodeChangeMessage
+  | WebhookReceivedMessage
   | SubscribedMessage
   | PongMessage
   | ConnectedMessage;
@@ -23,6 +24,18 @@ export interface NodeChangeMessage {
   data: unknown | null;
 }
 
+/**
+ * Webhook received notification for instant relay.
+ * Sent immediately when a webhook is received, before batch processing.
+ */
+export interface WebhookReceivedMessage {
+  type: 'webhook:received';
+  pluginName: string;
+  body: unknown;
+  headers: Record<string, string | string[] | undefined>;
+  timestamp: string;
+}
+
 /**
  * Subscription confirmation message.
  */
@@ -254,6 +267,34 @@ export class UDLWebSocketServer {
     });
   }
 
+  /**
+   * Broadcast a webhook received event to all connected clients.
+   * This is called immediately when a webhook is queued, before batch processing.
+   *
+   * @param webhook - The queued webhook to broadcast
+   */
+  broadcastWebhookReceived(webhook: {
+    pluginName: string;
+    body: unknown;
+    headers: Record<string, string | string[] | undefined>;
+    timestamp: number;
+  }): void {
+    const message: WebhookReceivedMessage = {
+      type: 'webhook:received',
+      pluginName: webhook.pluginName,
+      body: webhook.body,
+      headers: webhook.headers,
+      timestamp: new Date(webhook.timestamp).toISOString(),
+    };
+
+    this.wss.clients.forEach((ws) => {
+      const trackedWs = ws as TrackedWebSocket;
+      if (trackedWs.readyState === WebSocket.OPEN) {
+        this.send(trackedWs, message);
+      }
+    });
+  }
+
   /**
    * Send a message to a WebSocket client.
    */

From 3f9fb4c2757afa31c17fdce4601e335910c599b1 Mon Sep 17 00:00:00 2001
From: dawidurbanski <hi@dawidurbanski.com>
Date: Tue, 23 Dec 2025 12:30:29 +0100
Subject: [PATCH 37/46] feat(core): integrate instant webhook relay with remote
 sync

Wire up the instant webhook relay feature across remote sync,
loader, and start-server for complete local-first UDL workflow.

Remote sync:
- Cache fetched nodes via replaceAllCaches() for offline support
- Support onWebhookReceived callback for instant webhook processing

Loader:
- Use cache manager for plugin cache operations
- Add isLocal option to skip sourceNodes (data from remote)
- Initialize plugin caches even in local mode for persistence

Start-server:
- Set UDL_ENDPOINT env var for child processes
- Load plugins in local mode for webhook handler registration
- Process relayed webhooks locally using registered handlers
- Save affected plugin caches after webhook batch processing
- Wire up webhook:queued event to WebSocket broadcast
---
 packages/core/src/loader.ts       | 169 +++++++++++++++---------------
 packages/core/src/start-server.ts |  82 ++++++++++++++-
 packages/core/src/sync/remote.ts  |  30 +++++-
 3 files changed, 190 insertions(+), 91 deletions(-)

diff --git a/packages/core/src/loader.ts b/packages/core/src/loader.ts
index aa95b4a..eee1645 100644
--- a/packages/core/src/loader.ts
+++ b/packages/core/src/loader.ts
@@ -6,8 +6,13 @@ import { NodeStore } from '@/nodes/store.js';
 import { createNodeActions } from '@/nodes/actions/index.js';
 import { createNodeId, createContentDigest } from '@/nodes/utils/index.js';
 import { defaultStore } from '@/nodes/defaultStore.js';
-import { FileCacheStorage } from '@/cache/file-cache.js';
-import type { CacheStorage, CachedData } from '@/cache/types.js';
+import {
+  setStore as setCacheStore,
+  initPluginCache,
+  getPluginCache,
+  savePluginCache,
+} from '@/cache/manager.js';
+import type { CacheStorage } from '@/cache/types.js';
 import { defaultRegistry } from '@/references/index.js';
 import type {
   ReferenceResolverConfig,
@@ -579,6 +584,14 @@ export interface LoadPluginsOptions {
    * If not provided, uses the defaultWebhookRegistry singleton.
    */
   webhookRegistry?: WebhookRegistry;
+  /**
+   * Indicates this is a local development instance syncing from a remote UDL.
+   * When true, plugins are loaded and webhook handlers are registered,
+   * but sourceNodes is skipped (data comes from remote).
+   *
+   * @default false
+   */
+  isLocal?: boolean;
 }
 
 /** Maximum recursion depth for nested plugins */
@@ -712,6 +725,9 @@ export async function loadPlugins(
   const nodeStore = store ?? defaultStore;
   const codegenConfigs: PluginCodegenInfo[] = [];
 
+  // Set store reference on cache manager for webhook/remote sync cache updates
+  setCacheStore(nodeStore);
+
   if (_depth >= MAX_PLUGIN_DEPTH) {
     console.warn(
       `Maximum plugin recursion depth (${MAX_PLUGIN_DEPTH}) reached. Skipping nested plugins.`
@@ -769,11 +785,32 @@ export async function loadPlugins(
           await module.onLoad(context);
         }
 
-        // Execute sourceNodes hook and register indexes
-        if (module.sourceNodes && nodeStore) {
-          // Get the idField from plugin config (used for webhook lookups)
-          const pluginIdField = module.config?.idField;
+        // Get the idField from plugin config (used for webhook lookups)
+        const pluginIdField = module.config?.idField;
+
+        // Determine if caching is enabled for this plugin
+        // Plugin can provide custom CacheStorage or set to false to disable
+        const pluginCacheConfig = module.config?.cache;
+        const pluginCacheDisabled = pluginCacheConfig === false;
+        const shouldCache = cacheEnabled && !pluginCacheDisabled;
+        // Extract custom CacheStorage if provided (not false, not undefined)
+        const customCache =
+          typeof pluginCacheConfig === 'object' ? pluginCacheConfig : undefined;
+
+        // Cache is stored in the config directory that specified the plugin,
+        // not in the plugin's own directory. This ensures that when a feature
+        // uses a plugin, the cache lives alongside the feature's config.
+        // For nested plugins, the cache is stored in the parent plugin's directory.
+        const cacheLocation = cacheDir ?? pluginPath;
+
+        // Initialize cache for this plugin (needed for both local and remote modes)
+        // In local mode, replaceAllCaches() needs this to persist synced nodes
+        if (shouldCache) {
+          initPluginCache(actualPluginName, cacheLocation, customCache);
+        }
 
+        // Execute sourceNodes hook and register indexes (unless isLocal - data comes from remote)
+        if (module.sourceNodes && nodeStore && !options?.isLocal) {
           // Build indexes: idField is always indexed if specified
           const pluginDefaultIndexes = module.config?.indexes || [];
           const userIndexes =
@@ -786,38 +823,29 @@ export async function loadPlugins(
             ]),
           ];
 
-          // Determine if caching is enabled for this plugin
-          const pluginCacheDisabled = module.config?.cache === false;
-          const shouldCache = cacheEnabled && !pluginCacheDisabled;
-
-          // Cache is stored in the config directory that specified the plugin,
-          // not in the plugin's own directory. This ensures that when a feature
-          // uses a plugin, the cache lives alongside the feature's config.
-          // For nested plugins, the cache is stored in the parent plugin's directory.
-          const cacheLocation = cacheDir ?? pluginPath;
-
-          // Load plugin's cached nodes before sourceNodes
-          let pluginCache: FileCacheStorage | null = null;
+          // Load cached nodes before sourcing (if cache was initialized)
           if (shouldCache) {
-            pluginCache = new FileCacheStorage(cacheLocation);
-            const cached = await pluginCache.load();
-            if (cached && cached.nodes.length > 0) {
-              console.log(
-                `📂 [${actualPluginName}] Loading ${cached.nodes.length} nodes from cache...`
-              );
-              // Only load nodes owned by this plugin
-              const pluginNodes = cached.nodes.filter(
-                (node) => node.internal.owner === actualPluginName
-              );
-              for (const node of pluginNodes) {
-                nodeStore.set(node);
-              }
-              // Restore indexes for this plugin
-              for (const [nodeType, fieldNames] of Object.entries(
-                cached.indexes
-              )) {
-                for (const fieldName of fieldNames) {
-                  nodeStore.registerIndex(nodeType, fieldName);
+            const pluginCache = getPluginCache(actualPluginName);
+            if (pluginCache) {
+              const cached = await pluginCache.load();
+              if (cached && cached.nodes.length > 0) {
+                console.log(
+                  `📂 [${actualPluginName}] Loading ${cached.nodes.length} nodes from cache...`
+                );
+                // Only load nodes owned by this plugin
+                const pluginNodes = cached.nodes.filter(
+                  (node) => node.internal.owner === actualPluginName
+                );
+                for (const node of pluginNodes) {
+                  nodeStore.set(node);
+                }
+                // Restore indexes for this plugin
+                for (const [nodeType, fieldNames] of Object.entries(
+                  cached.indexes
+                )) {
+                  for (const fieldName of fieldNames) {
+                    nodeStore.registerIndex(nodeType, fieldName);
+                  }
                 }
               }
             }
@@ -838,57 +866,26 @@ export async function loadPlugins(
 
           registerPluginIndexes(nodeStore, actualPluginName, allIndexes);
 
-          // Register webhook handler for the plugin
-          // If plugin exports registerWebhookHandler, use it instead of default
-          if (module.registerWebhookHandler) {
-            registerPluginWebhookHandler(
-              webhookRegistry,
-              actualPluginName,
-              module.registerWebhookHandler
-            );
-          } else {
-            registerDefaultWebhook(
-              webhookRegistry,
-              actualPluginName,
-              pluginIdField
-            );
+          // Save plugin's nodes after sourceNodes (via CacheManager)
+          if (shouldCache) {
+            await savePluginCache(actualPluginName);
           }
+        }
 
-          // Save plugin's nodes after sourceNodes
-          if (shouldCache && pluginCache) {
-            // Get only nodes owned by this plugin
-            const allNodes = nodeStore.getAll();
-            const pluginNodes = allNodes.filter(
-              (node) => node.internal.owner === actualPluginName
-            );
-
-            // Get indexes for node types owned by this plugin
-            const pluginNodeTypes = new Set(
-              pluginNodes.map((n) => n.internal.type)
-            );
-            const indexes: Record<string, string[]> = {};
-            for (const nodeType of pluginNodeTypes) {
-              const registeredIndexes =
-                nodeStore.getRegisteredIndexes(nodeType);
-              if (registeredIndexes.length > 0) {
-                indexes[nodeType] = registeredIndexes;
-              }
-            }
-
-            const cacheData: CachedData = {
-              nodes: pluginNodes,
-              indexes,
-              meta: {
-                version: 1,
-                createdAt: Date.now(),
-                updatedAt: Date.now(),
-              },
-            };
-            await pluginCache.save(cacheData);
-            console.log(
-              `💾 [${actualPluginName}] Cached ${pluginNodes.length} nodes to disk`
-            );
-          }
+        // Register webhook handler for the plugin (always, regardless of isLocal)
+        // If plugin exports registerWebhookHandler, use it instead of default
+        if (module.registerWebhookHandler) {
+          registerPluginWebhookHandler(
+            webhookRegistry,
+            actualPluginName,
+            module.registerWebhookHandler
+          );
+        } else {
+          registerDefaultWebhook(
+            webhookRegistry,
+            actualPluginName,
+            pluginIdField
+          );
         }
 
         // Execute registerTypes hook
diff --git a/packages/core/src/start-server.ts b/packages/core/src/start-server.ts
index e3fbfd8..04a7c70 100644
--- a/packages/core/src/start-server.ts
+++ b/packages/core/src/start-server.ts
@@ -1,5 +1,5 @@
 import { loadAppConfig, loadPlugins } from '@/loader.js';
-import { createConfig } from '@/config.js';
+import { createConfig, UDL_ENDPOINT_ENV } from '@/config.js';
 import server from '@/server.js';
 import { rebuildHandler, getCurrentSchema } from '@/handlers/graphql.js';
 import { setReady } from '@/handlers/readiness.js';
@@ -19,7 +19,11 @@ import {
   setWebhookHooks,
   processWebhookBatch,
   OutboundWebhookManager,
+  defaultWebhookRegistry,
+  type QueuedWebhook,
 } from '@/webhooks/index.js';
+import { createNodeActions } from '@/nodes/actions/index.js';
+import type { WebhookHandlerContext } from '@/webhooks/types.js';
 import {
   UDLWebSocketServer,
   setDefaultWebSocketServer,
@@ -27,6 +31,7 @@ import {
 } from '@/websocket/index.js';
 import { initRemoteSync, isRemoteReachable } from '@/sync/remote.js';
 import type { UDLWebSocketClient } from '@/websocket/client.js';
+import { saveAffectedPlugins } from '@/cache/manager.js';
 
 export interface StartServerOptions {
   port?: number;
@@ -69,6 +74,10 @@ export async function startServer(options: StartServerOptions = {}) {
     endpoint,
   });
 
+  // Set UDL_ENDPOINT env var so child processes (e.g., Next.js) can use it
+  // This allows udl.query() to automatically use the correct endpoint
+  process.env[UDL_ENDPOINT_ENV] = endpoint;
+
   // Configure webhook queue with settings from config
   const webhookConfig = userConfig.remote?.webhooks ?? {};
   const webhookQueue = new WebhookQueue({
@@ -95,6 +104,15 @@ export async function startServer(options: StartServerOptions = {}) {
     );
   }
 
+  // Save affected plugin caches after webhook batch is processed
+  // This ensures webhook changes are persisted to disk for all instances
+  webhookQueue.on('webhook:batch-complete', (batch) => {
+    const affectedPluginNames = new Set<string>(
+      batch.webhooks.map((w: QueuedWebhook) => w.pluginName)
+    );
+    void saveAffectedPlugins(affectedPluginNames);
+  });
+
   console.log(
     `🔗 Webhook queue configured (debounce: ${webhookQueue.getDebounceMs()}ms, maxSize: ${webhookQueue.getMaxQueueSize()})`
   );
@@ -124,11 +142,66 @@ export async function startServer(options: StartServerOptions = {}) {
       shouldSyncFromRemote = true;
       console.log(`📡 Remote mode: syncing from ${remoteUrl}`);
 
+      // Load plugins in local mode - registers webhook handlers but skips sourceNodes
+      // (data comes from remote, but we need handlers to process relayed webhooks)
+      if (userConfig.plugins && userConfig.plugins.length > 0) {
+        console.log('📡 Loading plugins for webhook handlers...');
+        await loadPlugins(userConfig.plugins, {
+          appConfig: userConfig,
+          store: defaultStore,
+          cacheDir: process.cwd(),
+          isLocal: true,
+        });
+      }
+
       remoteWsClient = await initRemoteSync(
         {
           url: remoteUrl,
           // Note: WebSocket client uses sensible defaults (5s reconnect, 30s ping)
           // Custom client config can be added to RemoteSyncConfig if needed
+          onWebhookReceived: async (event) => {
+            // Process the webhook locally for instant node updates
+            const handler = defaultWebhookRegistry.getHandler(event.pluginName);
+            if (!handler) {
+              console.warn(
+                `⚠️ No handler for relayed webhook: ${event.pluginName}`
+              );
+              return;
+            }
+
+            // Create context for local processing
+            const actions = createNodeActions({
+              store: defaultStore,
+              owner: event.pluginName,
+            });
+            const context: WebhookHandlerContext = {
+              store: defaultStore,
+              actions,
+              rawBody: Buffer.from(
+                typeof event.body === 'string'
+                  ? event.body
+                  : JSON.stringify(event.body)
+              ),
+              body: event.body,
+            };
+
+            // Create minimal mock req/res for handler compatibility
+            const mockReq = { headers: event.headers } as never;
+            const mockRes = {
+              writeHead: () => mockRes,
+              end: () => mockRes,
+            } as never;
+
+            try {
+              await handler.handler(mockReq, mockRes, context);
+              console.log(`⚡ Processed relayed webhook: ${event.pluginName}`);
+            } catch (error) {
+              console.error(
+                `❌ Error processing relayed webhook ${event.pluginName}:`,
+                error
+              );
+            }
+          },
         },
         defaultStore
       );
@@ -495,11 +568,18 @@ export async function startServer(options: StartServerOptions = {}) {
     const wsServer = new UDLWebSocketServer(server, wsConfig);
     setDefaultWebSocketServer(wsServer);
 
+    // Wire up instant webhook relay to WebSocket subscribers
+    // This broadcasts webhooks immediately when received, before batch debounce
+    webhookQueue.on('webhook:queued', (webhook) => {
+      wsServer.broadcastWebhookReceived(webhook);
+    });
+
     const wsPort = wsConfig.port ?? port;
     const wsPath = wsConfig.path ?? '/ws';
     console.log(
       `🔌 WebSocket server available at ws://${host}:${wsPort}${wsPath}`
     );
+    console.log(`📡 Instant webhook relay enabled for WebSocket subscribers`);
   }
 
   return { server, config };
diff --git a/packages/core/src/sync/remote.ts b/packages/core/src/sync/remote.ts
index 5fcbd1a..76c7b41 100644
--- a/packages/core/src/sync/remote.ts
+++ b/packages/core/src/sync/remote.ts
@@ -1,7 +1,9 @@
 import type { NodeStore } from '@/nodes/store.js';
+import { replaceAllCaches } from '@/cache/manager.js';
 import {
   UDLWebSocketClient,
   type WebSocketClientConfig,
+  type WebhookReceivedEvent,
 } from '@/websocket/client.js';
 import type { SyncResponse } from '@/handlers/sync.js';
 
@@ -44,6 +46,11 @@ export interface RemoteSyncConfig {
   url: string;
   /** WebSocket configuration overrides */
   websocket?: Partial<Omit<WebSocketClientConfig, 'url'>>;
+  /**
+   * Callback invoked immediately when a webhook:received message is received.
+   * This enables instant processing of webhooks without waiting for batch debounce.
+   */
+  onWebhookReceived?: (event: WebhookReceivedEvent) => void | Promise<void>;
 }
 
 /**
@@ -93,20 +100,26 @@ export async function fetchRemoteNodes(
  * @param url - Base URL of the remote UDL server
  * @param store - Local node store to update with changes
  * @param config - Optional WebSocket configuration overrides
+ * @param onWebhookReceived - Optional callback for instant webhook processing
  * @returns The WebSocket client if connected, null if connection failed
  */
 export async function tryConnectRemoteWebSocket(
   url: string,
   store: NodeStore,
-  config?: Partial<Omit<WebSocketClientConfig, 'url'>>
+  config?: Partial<Omit<WebSocketClientConfig, 'url'>>,
+  onWebhookReceived?: (event: WebhookReceivedEvent) => void | Promise<void>
 ): Promise<UDLWebSocketClient | null> {
   // Convert HTTP URL to WebSocket URL
   const wsUrl = url.replace(/^http/, 'ws') + '/ws';
 
-  const client = new UDLWebSocketClient({
+  const clientConfig: WebSocketClientConfig = {
     url: wsUrl,
     ...config,
-  });
+  };
+  if (onWebhookReceived) {
+    clientConfig.onWebhookReceived = onWebhookReceived;
+  }
+  const client = new UDLWebSocketClient(clientConfig);
 
   try {
     await client.connect(store);
@@ -137,12 +150,21 @@ export async function initRemoteSync(
   // Fetch initial data
   await fetchRemoteNodes(config.url, store);
 
+  // Save fetched nodes to cache for offline support and faster restarts
+  // Replace entirely since remote is authoritative
+  await replaceAllCaches(store);
+
   // Try to connect WebSocket for real-time updates
   const wsClient = await tryConnectRemoteWebSocket(
     config.url,
     store,
-    config.websocket
+    config.websocket,
+    config.onWebhookReceived
   );
 
+  if (wsClient && config.onWebhookReceived) {
+    console.log('📡 Instant webhook relay enabled for local processing');
+  }
+
   return wsClient;
 }

From 9dfc079328e63b619d89f30495da7b67c5c88745 Mon Sep 17 00:00:00 2001
From: dawidurbanski <hi@dawidurbanski.com>
Date: Tue, 23 Dec 2025 12:30:39 +0100
Subject: [PATCH 38/46] feat(core): add webhook:queued event for instant relay

Emit webhook:queued event immediately when a webhook is queued,
before the debounce timer. This enables instant relay to WebSocket
subscribers without waiting for batch processing.
---
 packages/core/src/webhooks/queue.ts | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/packages/core/src/webhooks/queue.ts b/packages/core/src/webhooks/queue.ts
index 6dc7db0..154e74b 100644
--- a/packages/core/src/webhooks/queue.ts
+++ b/packages/core/src/webhooks/queue.ts
@@ -73,6 +73,8 @@ export interface WebhookQueueConfig {
  * Events emitted by the WebhookQueue.
  */
 export interface WebhookQueueEvents {
+  /** Emitted immediately when a webhook is queued (before debounce) */
+  'webhook:queued': (webhook: QueuedWebhook) => void;
   /** Emitted for each webhook when batch processing occurs */
   'webhook:process': (webhook: QueuedWebhook) => void;
   /** Emitted after a batch of webhooks has been processed successfully */
@@ -142,6 +144,9 @@ export class WebhookQueue extends EventEmitter {
       `📥 Webhook queued: ${webhook.pluginName} (${this.queue.length} in queue)`
     );
 
+    // Emit immediately for instant relay to WebSocket subscribers
+    this.emit('webhook:queued', webhook);
+
     // Check if we've hit max queue size
     if (this.queue.length >= this.maxQueueSize) {
       console.log(

From 5a7d4d64b590e6ea5903be2b04b288f932a39eeb Mon Sep 17 00:00:00 2001
From: dawidurbanski <hi@dawidurbanski.com>
Date: Tue, 23 Dec 2025 12:30:52 +0100
Subject: [PATCH 39/46] feat(adapter-nextjs): add config file support and
 UDL_ENDPOINT injection

Add shared config utilities and update commands to read port from
udl.config.ts and inject UDL_ENDPOINT env var to Next.js processes.

New utils/config.ts:
- loadPortFromConfig() reads port from udl.config.ts/.js/.mjs
- resolveUdlPort() with priority: CLI > config > default
- createNextEnv() builds env with UDL_ENDPOINT set

Commands updated:
- dev: resolve port from config, inject UDL_ENDPOINT to Next.js
- build: resolve port from config, inject UDL_ENDPOINT to Next.js
- start: resolve port from config, inject UDL_ENDPOINT to Next.js

This allows udl.query() to automatically use the correct endpoint
in Next.js code without manual configuration.
---
 packages/adapter-nextjs/src/commands/build.ts | 60 ++++++++-----
 packages/adapter-nextjs/src/commands/dev.ts   | 32 ++++---
 packages/adapter-nextjs/src/commands/start.ts | 32 ++++---
 packages/adapter-nextjs/src/utils/config.ts   | 84 +++++++++++++++++++
 4 files changed, 165 insertions(+), 43 deletions(-)
 create mode 100644 packages/adapter-nextjs/src/utils/config.ts

diff --git a/packages/adapter-nextjs/src/commands/build.ts b/packages/adapter-nextjs/src/commands/build.ts
index d02cb75..18f8bb5 100644
--- a/packages/adapter-nextjs/src/commands/build.ts
+++ b/packages/adapter-nextjs/src/commands/build.ts
@@ -5,14 +5,12 @@ import {
   type SpawnedProcess,
 } from '@/utils/spawn.js';
 import { waitForServer } from '@/utils/wait-for-ready.js';
-
-// ANSI color codes
-const CYAN = '\x1b[36m';
-const MAGENTA = '\x1b[35m';
-const GREEN = '\x1b[32m';
-const RESET = '\x1b[0m';
-
-const DEFAULT_UDL_PORT = 4000;
+import {
+  COLORS,
+  resolveUdlPort,
+  buildUdlEndpoint,
+  createNextEnv,
+} from '@/utils/config.js';
 
 /**
  * Configuration for runBuild, allowing dependency injection for testing.
@@ -34,7 +32,10 @@ export async function runBuild(
 ): Promise<void> {
   const exit = config?.exit ?? ((code: number) => process.exit(code));
   const waitFn = config?.waitForServer ?? waitForServer;
-  const udlPort = options.port ?? DEFAULT_UDL_PORT;
+
+  // Resolve UDL port from CLI options or config file
+  const udlPort = await resolveUdlPort(options.port);
+  const udlEndpoint = buildUdlEndpoint(udlPort);
 
   const processes: SpawnedProcess[] = [];
 
@@ -44,25 +45,34 @@ export async function runBuild(
 
   try {
     // Step 1: Start UDL server in background
-    console.log(`${GREEN}Starting UDL server...${RESET}`);
+    console.log(`${COLORS.GREEN}Starting UDL server...${COLORS.RESET}`);
+    const udlArgs = ['universal-data-layer'];
+    // Pass --port only if explicitly provided via CLI (to override config)
+    if (options.port !== undefined) {
+      udlArgs.push('--port', String(options.port));
+    }
     const udlProcess = spawnWithPrefix(
       'npx',
-      ['universal-data-layer', '--port', String(udlPort)],
-      `${CYAN}[udl]${RESET}`
+      udlArgs,
+      `${COLORS.CYAN}[udl]${COLORS.RESET}`
     );
     processes.push(udlProcess);
 
     // Step 2: Wait for UDL server to be ready
-    console.log(`${GREEN}Waiting for UDL server to be ready...${RESET}`);
+    console.log(
+      `${COLORS.GREEN}Waiting for UDL server to be ready...${COLORS.RESET}`
+    );
     await waitFn(udlPort);
-    console.log(`${GREEN}UDL server is ready on port ${udlPort}${RESET}`);
+    console.log(
+      `${COLORS.GREEN}UDL server is ready on port ${udlPort}${COLORS.RESET}`
+    );
 
     // Step 3: Run codegen
-    console.log(`${GREEN}Running codegen...${RESET}`);
+    console.log(`${COLORS.GREEN}Running codegen...${COLORS.RESET}`);
     const codegenExitCode = await runCommand(
       'npx',
       ['udl-codegen'],
-      `${CYAN}[codegen]${RESET}`
+      `${COLORS.CYAN}[codegen]${COLORS.RESET}`
     );
 
     if (codegenExitCode !== 0) {
@@ -71,14 +81,15 @@ export async function runBuild(
       exit(codegenExitCode);
       return;
     }
-    console.log(`${GREEN}Codegen completed successfully${RESET}`);
+    console.log(`${COLORS.GREEN}Codegen completed successfully${COLORS.RESET}`);
 
-    // Step 4: Run next build
-    console.log(`${GREEN}Building Next.js...${RESET}`);
+    // Step 4: Run next build with UDL_ENDPOINT set
+    console.log(`${COLORS.GREEN}Building Next.js...${COLORS.RESET}`);
     const nextBuildExitCode = await runCommand(
       'npx',
       ['next', 'build', ...nextArgs],
-      `${MAGENTA}[next]${RESET}`
+      `${COLORS.MAGENTA}[next]${COLORS.RESET}`,
+      { env: createNextEnv(udlEndpoint) }
     );
 
     if (nextBuildExitCode !== 0) {
@@ -87,7 +98,9 @@ export async function runBuild(
       exit(nextBuildExitCode);
       return;
     }
-    console.log(`${GREEN}Next.js build completed successfully${RESET}`);
+    console.log(
+      `${COLORS.GREEN}Next.js build completed successfully${COLORS.RESET}`
+    );
 
     // Step 5: Cleanup and exit
     await cleanup();
@@ -107,10 +120,11 @@ export async function runBuild(
 function runCommand(
   command: string,
   args: string[],
-  prefix: string
+  prefix: string,
+  options?: { env?: NodeJS.ProcessEnv }
 ): Promise<number> {
   return new Promise((resolve) => {
-    const spawned = spawnWithPrefix(command, args, prefix);
+    const spawned = spawnWithPrefix(command, args, prefix, options);
 
     spawned.process.on('exit', (code) => {
       resolve(code ?? 1);
diff --git a/packages/adapter-nextjs/src/commands/dev.ts b/packages/adapter-nextjs/src/commands/dev.ts
index 2802d5c..c39d414 100644
--- a/packages/adapter-nextjs/src/commands/dev.ts
+++ b/packages/adapter-nextjs/src/commands/dev.ts
@@ -4,13 +4,13 @@ import {
   killAll,
   type SpawnedProcess,
 } from '@/utils/spawn.js';
-
-// ANSI color codes
-const CYAN = '\x1b[36m';
-const MAGENTA = '\x1b[35m';
-const RESET = '\x1b[0m';
-
-const DEFAULT_NEXT_PORT = 3000;
+import {
+  COLORS,
+  DEFAULT_NEXT_PORT,
+  resolveUdlPort,
+  buildUdlEndpoint,
+  createNextEnv,
+} from '@/utils/config.js';
 
 /**
  * Configuration for runDev, allowing dependency injection for testing.
@@ -54,20 +54,32 @@ export async function runDev(
   process.on('SIGINT', handleSignal);
   process.on('SIGTERM', handleSignal);
 
+  // Resolve UDL port from CLI options or config file
+  const udlPort = await resolveUdlPort(options.port);
+  const udlEndpoint = buildUdlEndpoint(udlPort);
+
   // Spawn UDL server
   const udlArgs = ['universal-data-layer'];
+  // Pass --port only if explicitly provided via CLI (to override config)
   if (options.port !== undefined) {
     udlArgs.push('--port', String(options.port));
   }
-  const udlProcess = spawnWithPrefix('npx', udlArgs, `${CYAN}[udl]${RESET}`);
+  const udlProcess = spawnWithPrefix(
+    'npx',
+    udlArgs,
+    `${COLORS.CYAN}[udl]${COLORS.RESET}`
+  );
   processes.push(udlProcess);
 
-  // Spawn Next.js dev server
+  // Spawn Next.js dev server with UDL_ENDPOINT set
   const nextPortArgs = ['--port', String(nextPort)];
   const nextProcess = spawnWithPrefix(
     'npx',
     ['next', 'dev', ...nextPortArgs, ...nextArgs],
-    `${MAGENTA}[next]${RESET}`
+    `${COLORS.MAGENTA}[next]${COLORS.RESET}`,
+    {
+      env: createNextEnv(udlEndpoint),
+    }
   );
   processes.push(nextProcess);
 
diff --git a/packages/adapter-nextjs/src/commands/start.ts b/packages/adapter-nextjs/src/commands/start.ts
index 7f16830..7620fe1 100644
--- a/packages/adapter-nextjs/src/commands/start.ts
+++ b/packages/adapter-nextjs/src/commands/start.ts
@@ -4,13 +4,13 @@ import {
   killAll,
   type SpawnedProcess,
 } from '@/utils/spawn.js';
-
-// ANSI color codes
-const CYAN = '\x1b[36m';
-const MAGENTA = '\x1b[35m';
-const RESET = '\x1b[0m';
-
-const DEFAULT_NEXT_PORT = 3000;
+import {
+  COLORS,
+  DEFAULT_NEXT_PORT,
+  resolveUdlPort,
+  buildUdlEndpoint,
+  createNextEnv,
+} from '@/utils/config.js';
 
 /**
  * Configuration for runStart, allowing dependency injection for testing.
@@ -54,20 +54,32 @@ export async function runStart(
   process.on('SIGINT', handleSignal);
   process.on('SIGTERM', handleSignal);
 
+  // Resolve UDL port from CLI options or config file
+  const udlPort = await resolveUdlPort(options.port);
+  const udlEndpoint = buildUdlEndpoint(udlPort);
+
   // Spawn UDL server
   const udlArgs = ['universal-data-layer'];
+  // Pass --port only if explicitly provided via CLI (to override config)
   if (options.port !== undefined) {
     udlArgs.push('--port', String(options.port));
   }
-  const udlProcess = spawnWithPrefix('npx', udlArgs, `${CYAN}[udl]${RESET}`);
+  const udlProcess = spawnWithPrefix(
+    'npx',
+    udlArgs,
+    `${COLORS.CYAN}[udl]${COLORS.RESET}`
+  );
   processes.push(udlProcess);
 
-  // Spawn Next.js production server
+  // Spawn Next.js production server with UDL_ENDPOINT set
   const nextPortArgs = ['--port', String(nextPort)];
   const nextProcess = spawnWithPrefix(
     'npx',
     ['next', 'start', ...nextPortArgs, ...nextArgs],
-    `${MAGENTA}[next]${RESET}`
+    `${COLORS.MAGENTA}[next]${COLORS.RESET}`,
+    {
+      env: createNextEnv(udlEndpoint),
+    }
   );
   processes.push(nextProcess);
 
diff --git a/packages/adapter-nextjs/src/utils/config.ts b/packages/adapter-nextjs/src/utils/config.ts
new file mode 100644
index 0000000..a9a9d2a
--- /dev/null
+++ b/packages/adapter-nextjs/src/utils/config.ts
@@ -0,0 +1,84 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+// ANSI color codes
+export const COLORS = {
+  CYAN: '\x1b[36m',
+  MAGENTA: '\x1b[35m',
+  GREEN: '\x1b[32m',
+  RESET: '\x1b[0m',
+} as const;
+
+// Default ports
+export const DEFAULT_NEXT_PORT = 3000;
+export const DEFAULT_UDL_PORT = 4000;
+
+// Environment variable name for UDL endpoint
+export const UDL_ENDPOINT_ENV = 'UDL_ENDPOINT';
+
+/**
+ * Load the port from udl.config.ts if it exists.
+ * Returns undefined if config not found or port not specified.
+ */
+export async function loadPortFromConfig(): Promise<number | undefined> {
+  const configFiles = ['udl.config.ts', 'udl.config.js', 'udl.config.mjs'];
+
+  for (const configFile of configFiles) {
+    const configPath = join(process.cwd(), configFile);
+
+    if (existsSync(configPath)) {
+      try {
+        // For TypeScript files, we need tsx to be available
+        if (configFile.endsWith('.ts')) {
+          const { register } = await import('tsx/esm/api');
+          const unregister = register();
+          try {
+            const fileUrl = pathToFileURL(configPath).href;
+            const module = await import(fileUrl);
+            return module.config?.port;
+          } finally {
+            unregister();
+          }
+        } else {
+          const fileUrl = pathToFileURL(configPath).href;
+          const module = await import(fileUrl);
+          return module.config?.port;
+        }
+      } catch {
+        // Ignore errors, fall back to default
+      }
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Build the UDL GraphQL endpoint URL from port.
+ */
+export function buildUdlEndpoint(port: number): string {
+  return `http://localhost:${port}/graphql`;
+}
+
+/**
+ * Resolve the UDL port from CLI options and config file.
+ * Priority: CLI option > config file > default
+ */
+export async function resolveUdlPort(cliPort?: number): Promise<number> {
+  if (cliPort !== undefined) {
+    return cliPort;
+  }
+  const configPort = await loadPortFromConfig();
+  return configPort ?? DEFAULT_UDL_PORT;
+}
+
+/**
+ * Create environment variables for spawning Next.js with UDL_ENDPOINT set.
+ */
+export function createNextEnv(udlEndpoint: string): NodeJS.ProcessEnv {
+  return {
+    ...process.env,
+    [UDL_ENDPOINT_ENV]: udlEndpoint,
+  };
+}

From 660d7d1c285ee6201d4e834c9d813a03b5b8520a Mon Sep 17 00:00:00 2001
From: dawidurbanski <hi@dawidurbanski.com>
Date: Tue, 23 Dec 2025 12:31:05 +0100
Subject: [PATCH 40/46] test: add comprehensive tests for cache manager,
 config, and webhooks

Core tests:
- cache/manager.test.ts: cache manager registration and operations
- config.test.ts: UDL_ENDPOINT env var, resetConfig, isConfigInitialized
- sync/remote.test.ts: onWebhookReceived callback, cache persistence
- webhooks/queue.test.ts: webhook:queued event emission
- websocket/client.test.ts: webhook:received handling, onWebhookReceived
- websocket/server.test.ts: broadcastWebhookReceived
- loader.test.ts: isLocal option, cache manager integration

Adapter-nextjs tests:
- utils/config.test.ts: loadPortFromConfig, resolveUdlPort
- dev.test.ts: config loading, UDL_ENDPOINT injection
- build.test.ts: config loading, UDL_ENDPOINT injection
- start.test.ts: config loading, UDL_ENDPOINT injection
---
 .../adapter-nextjs/tests/unit/build.test.ts   |  42 +-
 .../adapter-nextjs/tests/unit/dev.test.ts     |  61 ++-
 .../adapter-nextjs/tests/unit/start.test.ts   |  61 ++-
 .../tests/unit/utils/config.test.ts           | 293 +++++++++++++
 .../core/tests/integration/loader.test.ts     | 251 ++++++++++++
 .../core/tests/unit/cache/manager.test.ts     | 384 ++++++++++++++++++
 packages/core/tests/unit/config.test.ts       |  85 +++-
 packages/core/tests/unit/sync/remote.test.ts  | 157 +++++++
 .../core/tests/unit/webhooks/queue.test.ts    |  96 +++--
 .../core/tests/unit/websocket/client.test.ts  | 265 ++++++++++++
 .../core/tests/unit/websocket/server.test.ts  |  64 +++
 11 files changed, 1699 insertions(+), 60 deletions(-)
 create mode 100644 packages/adapter-nextjs/tests/unit/utils/config.test.ts
 create mode 100644 packages/core/tests/unit/cache/manager.test.ts

diff --git a/packages/adapter-nextjs/tests/unit/build.test.ts b/packages/adapter-nextjs/tests/unit/build.test.ts
index abc35be..a2ad82f 100644
--- a/packages/adapter-nextjs/tests/unit/build.test.ts
+++ b/packages/adapter-nextjs/tests/unit/build.test.ts
@@ -20,6 +20,26 @@ vi.mock('@/utils/wait-for-ready.js', async (importOriginal) => {
   };
 });
 
+// Mock the config module
+vi.mock('@/utils/config.js', () => ({
+  COLORS: {
+    CYAN: '\x1b[36m',
+    MAGENTA: '\x1b[35m',
+    GREEN: '\x1b[32m',
+    RESET: '\x1b[0m',
+  },
+  DEFAULT_NEXT_PORT: 3000,
+  DEFAULT_UDL_PORT: 4000,
+  UDL_ENDPOINT_ENV: 'UDL_ENDPOINT',
+  // Mock resolveUdlPort to return default port (simulating no config file)
+  resolveUdlPort: vi.fn(async (cliPort?: number) => cliPort ?? 4000),
+  buildUdlEndpoint: vi.fn((port: number) => `http://localhost:${port}/graphql`),
+  createNextEnv: vi.fn((udlEndpoint: string) => ({
+    ...process.env,
+    UDL_ENDPOINT: udlEndpoint,
+  })),
+}));
+
 const mockSpawnWithPrefix = vi.mocked(spawnModule.spawnWithPrefix);
 const mockKillAll = vi.mocked(spawnModule.killAll);
 
@@ -85,15 +105,16 @@ describe('runBuild', () => {
     vi.restoreAllMocks();
   });
 
-  it('should spawn UDL server with default port', async () => {
+  it('should spawn UDL server without explicit port (uses UDL default)', async () => {
     await runBuild({}, [], {
       exit: mockExit,
       waitForServer: mockWaitForServer,
     });
 
+    // When no port is specified, UDL uses its own default (from config or 4000)
     expect(mockSpawnWithPrefix).toHaveBeenCalledWith(
       'npx',
-      ['universal-data-layer', '--port', '4000'],
+      ['universal-data-layer'],
       expect.stringContaining('[udl]')
     );
   });
@@ -129,7 +150,8 @@ describe('runBuild', () => {
     expect(mockSpawnWithPrefix).toHaveBeenCalledWith(
       'npx',
       ['udl-codegen'],
-      expect.stringContaining('[codegen]')
+      expect.stringContaining('[codegen]'),
+      undefined
     );
   });
 
@@ -142,7 +164,12 @@ describe('runBuild', () => {
     expect(mockSpawnWithPrefix).toHaveBeenCalledWith(
       'npx',
       ['next', 'build'],
-      expect.stringContaining('[next]')
+      expect.stringContaining('[next]'),
+      expect.objectContaining({
+        env: expect.objectContaining({
+          UDL_ENDPOINT: 'http://localhost:4000/graphql',
+        }),
+      })
     );
   });
 
@@ -155,7 +182,12 @@ describe('runBuild', () => {
     expect(mockSpawnWithPrefix).toHaveBeenCalledWith(
       'npx',
       ['next', 'build', '--debug'],
-      expect.stringContaining('[next]')
+      expect.stringContaining('[next]'),
+      expect.objectContaining({
+        env: expect.objectContaining({
+          UDL_ENDPOINT: 'http://localhost:4000/graphql',
+        }),
+      })
     );
   });
 
diff --git a/packages/adapter-nextjs/tests/unit/dev.test.ts b/packages/adapter-nextjs/tests/unit/dev.test.ts
index bbf7dbe..858f2a4 100644
--- a/packages/adapter-nextjs/tests/unit/dev.test.ts
+++ b/packages/adapter-nextjs/tests/unit/dev.test.ts
@@ -10,6 +10,26 @@ vi.mock('@/utils/spawn.js', () => ({
   killAll: vi.fn().mockResolvedValue(undefined),
 }));
 
+// Mock the config module
+vi.mock('@/utils/config.js', () => ({
+  COLORS: {
+    CYAN: '\x1b[36m',
+    MAGENTA: '\x1b[35m',
+    GREEN: '\x1b[32m',
+    RESET: '\x1b[0m',
+  },
+  DEFAULT_NEXT_PORT: 3000,
+  DEFAULT_UDL_PORT: 4000,
+  UDL_ENDPOINT_ENV: 'UDL_ENDPOINT',
+  // Mock resolveUdlPort to return default port (simulating no config file)
+  resolveUdlPort: vi.fn(async (cliPort?: number) => cliPort ?? 4000),
+  buildUdlEndpoint: vi.fn((port: number) => `http://localhost:${port}/graphql`),
+  createNextEnv: vi.fn((udlEndpoint: string) => ({
+    ...process.env,
+    UDL_ENDPOINT: udlEndpoint,
+  })),
+}));
+
 const mockSpawnWithPrefix = vi.mocked(spawnModule.spawnWithPrefix);
 const mockKillAll = vi.mocked(spawnModule.killAll);
 
@@ -140,7 +160,12 @@ describe('runDev', () => {
     expect(mockSpawnWithPrefix).toHaveBeenCalledWith(
       'npx',
       ['next', 'dev', '--port', '3000'],
-      expect.stringContaining('[next]')
+      expect.stringContaining('[next]'),
+      expect.objectContaining({
+        env: expect.objectContaining({
+          UDL_ENDPOINT: 'http://localhost:4000/graphql',
+        }),
+      })
     );
   });
 
@@ -156,7 +181,12 @@ describe('runDev', () => {
     expect(mockSpawnWithPrefix).toHaveBeenCalledWith(
       'npx',
       ['next', 'dev', '--port', '3001'],
-      expect.stringContaining('[next]')
+      expect.stringContaining('[next]'),
+      expect.objectContaining({
+        env: expect.objectContaining({
+          UDL_ENDPOINT: 'http://localhost:4000/graphql',
+        }),
+      })
     );
   });
 
@@ -172,7 +202,12 @@ describe('runDev', () => {
     expect(mockSpawnWithPrefix).toHaveBeenCalledWith(
       'npx',
       ['next', 'dev', '--port', '3000', '--turbo', '--experimental-https'],
-      expect.stringContaining('[next]')
+      expect.stringContaining('[next]'),
+      expect.objectContaining({
+        env: expect.objectContaining({
+          UDL_ENDPOINT: 'http://localhost:4000/graphql',
+        }),
+      })
     );
   });
 
@@ -258,6 +293,11 @@ describe('runDev', () => {
       signal: abortController.signal,
     });
 
+    // Wait for spawn calls to complete (handlers to be registered)
+    await vi.waitFor(() =>
+      expect(mockSpawnWithPrefix).toHaveBeenCalledTimes(2)
+    );
+
     // Simulate UDL process exiting with code 1
     mockUdlProcess.emit('exit', 1, null);
     await devPromise;
@@ -275,6 +315,11 @@ describe('runDev', () => {
       signal: abortController.signal,
     });
 
+    // Wait for spawn calls to complete (handlers to be registered)
+    await vi.waitFor(() =>
+      expect(mockSpawnWithPrefix).toHaveBeenCalledTimes(2)
+    );
+
     // Simulate Next.js process exiting with code 2
     mockNextProcess.emit('exit', 2, null);
     await devPromise;
@@ -292,6 +337,11 @@ describe('runDev', () => {
       signal: abortController.signal,
     });
 
+    // Wait for spawn calls to complete (handlers to be registered)
+    await vi.waitFor(() =>
+      expect(mockSpawnWithPrefix).toHaveBeenCalledTimes(2)
+    );
+
     // Simulate process exiting with null code (killed by signal)
     mockUdlProcess.emit('exit', null, 'SIGKILL');
     await devPromise;
@@ -362,6 +412,11 @@ describe('runDev', () => {
       signal: abortController.signal,
     });
 
+    // Wait for spawn calls to complete
+    await vi.waitFor(() =>
+      expect(mockSpawnWithPrefix).toHaveBeenCalledTimes(2)
+    );
+
     // Abort directly without triggering exit
     abortController.abort();
     await devPromise;
diff --git a/packages/adapter-nextjs/tests/unit/start.test.ts b/packages/adapter-nextjs/tests/unit/start.test.ts
index 771d9c3..321b90d 100644
--- a/packages/adapter-nextjs/tests/unit/start.test.ts
+++ b/packages/adapter-nextjs/tests/unit/start.test.ts
@@ -10,6 +10,26 @@ vi.mock('@/utils/spawn.js', () => ({
   killAll: vi.fn().mockResolvedValue(undefined),
 }));
 
+// Mock the config module
+vi.mock('@/utils/config.js', () => ({
+  COLORS: {
+    CYAN: '\x1b[36m',
+    MAGENTA: '\x1b[35m',
+    GREEN: '\x1b[32m',
+    RESET: '\x1b[0m',
+  },
+  DEFAULT_NEXT_PORT: 3000,
+  DEFAULT_UDL_PORT: 4000,
+  UDL_ENDPOINT_ENV: 'UDL_ENDPOINT',
+  // Mock resolveUdlPort to return default port (simulating no config file)
+  resolveUdlPort: vi.fn(async (cliPort?: number) => cliPort ?? 4000),
+  buildUdlEndpoint: vi.fn((port: number) => `http://localhost:${port}/graphql`),
+  createNextEnv: vi.fn((udlEndpoint: string) => ({
+    ...process.env,
+    UDL_ENDPOINT: udlEndpoint,
+  })),
+}));
+
 const mockSpawnWithPrefix = vi.mocked(spawnModule.spawnWithPrefix);
 const mockKillAll = vi.mocked(spawnModule.killAll);
 
@@ -140,7 +160,12 @@ describe('runStart', () => {
     expect(mockSpawnWithPrefix).toHaveBeenCalledWith(
       'npx',
       ['next', 'start', '--port', '3000'],
-      expect.stringContaining('[next]')
+      expect.stringContaining('[next]'),
+      expect.objectContaining({
+        env: expect.objectContaining({
+          UDL_ENDPOINT: 'http://localhost:4000/graphql',
+        }),
+      })
     );
   });
 
@@ -156,7 +181,12 @@ describe('runStart', () => {
     expect(mockSpawnWithPrefix).toHaveBeenCalledWith(
       'npx',
       ['next', 'start', '--port', '3001'],
-      expect.stringContaining('[next]')
+      expect.stringContaining('[next]'),
+      expect.objectContaining({
+        env: expect.objectContaining({
+          UDL_ENDPOINT: 'http://localhost:4000/graphql',
+        }),
+      })
     );
   });
 
@@ -172,7 +202,12 @@ describe('runStart', () => {
     expect(mockSpawnWithPrefix).toHaveBeenCalledWith(
       'npx',
       ['next', 'start', '--port', '3000', '--keepAliveTimeout', '5000'],
-      expect.stringContaining('[next]')
+      expect.stringContaining('[next]'),
+      expect.objectContaining({
+        env: expect.objectContaining({
+          UDL_ENDPOINT: 'http://localhost:4000/graphql',
+        }),
+      })
     );
   });
 
@@ -258,6 +293,11 @@ describe('runStart', () => {
       signal: abortController.signal,
     });
 
+    // Wait for spawn calls to complete (handlers to be registered)
+    await vi.waitFor(() =>
+      expect(mockSpawnWithPrefix).toHaveBeenCalledTimes(2)
+    );
+
     // Simulate UDL process exiting with code 1
     mockUdlProcess.emit('exit', 1, null);
     await startPromise;
@@ -275,6 +315,11 @@ describe('runStart', () => {
       signal: abortController.signal,
     });
 
+    // Wait for spawn calls to complete (handlers to be registered)
+    await vi.waitFor(() =>
+      expect(mockSpawnWithPrefix).toHaveBeenCalledTimes(2)
+    );
+
     // Simulate Next.js process exiting with code 2
     mockNextProcess.emit('exit', 2, null);
     await startPromise;
@@ -292,6 +337,11 @@ describe('runStart', () => {
       signal: abortController.signal,
     });
 
+    // Wait for spawn calls to complete (handlers to be registered)
+    await vi.waitFor(() =>
+      expect(mockSpawnWithPrefix).toHaveBeenCalledTimes(2)
+    );
+
     // Simulate process exiting with null code (killed by signal)
     mockUdlProcess.emit('exit', null, 'SIGKILL');
     await startPromise;
@@ -362,6 +412,11 @@ describe('runStart', () => {
       signal: abortController.signal,
     });
 
+    // Wait for spawn calls to complete
+    await vi.waitFor(() =>
+      expect(mockSpawnWithPrefix).toHaveBeenCalledTimes(2)
+    );
+
     // Abort directly without triggering exit
     abortController.abort();
     await startPromise;
diff --git a/packages/adapter-nextjs/tests/unit/utils/config.test.ts b/packages/adapter-nextjs/tests/unit/utils/config.test.ts
new file mode 100644
index 0000000..7e6c712
--- /dev/null
+++ b/packages/adapter-nextjs/tests/unit/utils/config.test.ts
@@ -0,0 +1,293 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import {
+  COLORS,
+  DEFAULT_NEXT_PORT,
+  DEFAULT_UDL_PORT,
+  UDL_ENDPOINT_ENV,
+  loadPortFromConfig,
+  buildUdlEndpoint,
+  resolveUdlPort,
+  createNextEnv,
+} from '@/utils/config';
+
+vi.mock('node:fs', () => ({
+  existsSync: vi.fn(),
+}));
+
+describe('config utils', () => {
+  describe('constants', () => {
+    it('exports COLORS with correct ANSI codes', () => {
+      expect(COLORS).toEqual({
+        CYAN: '\x1b[36m',
+        MAGENTA: '\x1b[35m',
+        GREEN: '\x1b[32m',
+        RESET: '\x1b[0m',
+      });
+    });
+
+    it('exports DEFAULT_NEXT_PORT as 3000', () => {
+      expect(DEFAULT_NEXT_PORT).toBe(3000);
+    });
+
+    it('exports DEFAULT_UDL_PORT as 4000', () => {
+      expect(DEFAULT_UDL_PORT).toBe(4000);
+    });
+
+    it('exports UDL_ENDPOINT_ENV as "UDL_ENDPOINT"', () => {
+      expect(UDL_ENDPOINT_ENV).toBe('UDL_ENDPOINT');
+    });
+  });
+
+  describe('buildUdlEndpoint', () => {
+    it('builds endpoint URL from port', () => {
+      expect(buildUdlEndpoint(4000)).toBe('http://localhost:4000/graphql');
+    });
+
+    it('works with different ports', () => {
+      expect(buildUdlEndpoint(5000)).toBe('http://localhost:5000/graphql');
+    });
+  });
+
+  describe('createNextEnv', () => {
+    it('creates env with UDL_ENDPOINT set', () => {
+      const env = createNextEnv('http://localhost:4000/graphql');
+      expect(env['UDL_ENDPOINT']).toBe('http://localhost:4000/graphql');
+    });
+
+    it('preserves existing environment variables', () => {
+      const originalEnv = process.env;
+      const testKey = '__TEST_VAR_CONFIG__';
+      process.env[testKey] = 'test-value';
+
+      try {
+        const env = createNextEnv('http://localhost:4000/graphql');
+        expect(env[testKey]).toBe('test-value');
+      } finally {
+        delete process.env[testKey];
+        process.env = originalEnv;
+      }
+    });
+  });
+
+  describe('loadPortFromConfig', () => {
+    const mockExistsSync = existsSync as ReturnType<typeof vi.fn>;
+
+    beforeEach(() => {
+      vi.resetModules();
+      mockExistsSync.mockReset();
+    });
+
+    afterEach(() => {
+      vi.restoreAllMocks();
+    });
+
+    it('returns undefined when no config file exists', async () => {
+      mockExistsSync.mockReturnValue(false);
+
+      const port = await loadPortFromConfig();
+      expect(port).toBeUndefined();
+    });
+
+    it('loads port from udl.config.ts file', async () => {
+      const configPath = join(process.cwd(), 'udl.config.ts');
+      mockExistsSync.mockImplementation((path) => path === configPath);
+
+      // Mock tsx/esm/api
+      vi.doMock('tsx/esm/api', () => ({
+        register: () => vi.fn(), // returns unregister function
+      }));
+
+      // Mock dynamic import of config file
+      const fileUrl = pathToFileURL(configPath).href;
+      vi.doMock(fileUrl, () => ({
+        config: { port: 5000 },
+      }));
+
+      const { loadPortFromConfig: loadFn } = await import('@/utils/config');
+      const port = await loadFn();
+      expect(port).toBe(5000);
+    });
+
+    it('loads port from udl.config.js file', async () => {
+      const jsConfigPath = join(process.cwd(), 'udl.config.js');
+      mockExistsSync.mockImplementation((path) => path === jsConfigPath);
+
+      // Mock dynamic import of config file
+      const fileUrl = pathToFileURL(jsConfigPath).href;
+      vi.doMock(fileUrl, () => ({
+        config: { port: 6000 },
+      }));
+
+      const { loadPortFromConfig: loadFn } = await import('@/utils/config');
+      const port = await loadFn();
+      expect(port).toBe(6000);
+    });
+
+    it('loads port from udl.config.mjs file', async () => {
+      const mjsConfigPath = join(process.cwd(), 'udl.config.mjs');
+      mockExistsSync.mockImplementation((path) => path === mjsConfigPath);
+
+      // Mock dynamic import of config file
+      const fileUrl = pathToFileURL(mjsConfigPath).href;
+      vi.doMock(fileUrl, () => ({
+        config: { port: 7000 },
+      }));
+
+      const { loadPortFromConfig: loadFn } = await import('@/utils/config');
+      const port = await loadFn();
+      expect(port).toBe(7000);
+    });
+
+    it('returns undefined when config has no port', async () => {
+      const jsConfigPath = join(process.cwd(), 'udl.config.js');
+      mockExistsSync.mockImplementation((path) => path === jsConfigPath);
+
+      // Mock dynamic import of config file with no port
+      const fileUrl = pathToFileURL(jsConfigPath).href;
+      vi.doMock(fileUrl, () => ({
+        config: {},
+      }));
+
+      const { loadPortFromConfig: loadFn } = await import('@/utils/config');
+      const port = await loadFn();
+      expect(port).toBeUndefined();
+    });
+
+    it('returns undefined when config is undefined', async () => {
+      const jsConfigPath = join(process.cwd(), 'udl.config.js');
+      mockExistsSync.mockImplementation((path) => path === jsConfigPath);
+
+      // Mock dynamic import of config file with no config export
+      const fileUrl = pathToFileURL(jsConfigPath).href;
+      vi.doMock(fileUrl, () => ({}));
+
+      const { loadPortFromConfig: loadFn } = await import('@/utils/config');
+      const port = await loadFn();
+      expect(port).toBeUndefined();
+    });
+
+    it('returns undefined when import throws an error', async () => {
+      const jsConfigPath = join(process.cwd(), 'udl.config.js');
+      mockExistsSync.mockImplementation((path) => path === jsConfigPath);
+
+      // Mock dynamic import that throws
+      const fileUrl = pathToFileURL(jsConfigPath).href;
+      vi.doMock(fileUrl, () => {
+        throw new Error('Module not found');
+      });
+
+      const { loadPortFromConfig: loadFn } = await import('@/utils/config');
+      const port = await loadFn();
+      expect(port).toBeUndefined();
+    });
+
+    it('returns undefined when tsx import throws an error', async () => {
+      const tsConfigPath = join(process.cwd(), 'udl.config.ts');
+      mockExistsSync.mockImplementation((path) => path === tsConfigPath);
+
+      // Mock tsx/esm/api to throw
+      vi.doMock('tsx/esm/api', () => {
+        throw new Error('tsx not available');
+      });
+
+      const { loadPortFromConfig: loadFn } = await import('@/utils/config');
+      const port = await loadFn();
+      expect(port).toBeUndefined();
+    });
+
+    it('calls unregister after loading TS config', async () => {
+      const tsConfigPath = join(process.cwd(), 'udl.config.ts');
+      mockExistsSync.mockImplementation((path) => path === tsConfigPath);
+
+      const unregisterMock = vi.fn();
+      vi.doMock('tsx/esm/api', () => ({
+        register: () => unregisterMock,
+      }));
+
+      const fileUrl = pathToFileURL(tsConfigPath).href;
+      vi.doMock(fileUrl, () => ({
+        config: { port: 5000 },
+      }));
+
+      const { loadPortFromConfig: loadFn } = await import('@/utils/config');
+      await loadFn();
+      expect(unregisterMock).toHaveBeenCalled();
+    });
+
+    it('calls unregister even when config import throws', async () => {
+      const tsConfigPath = join(process.cwd(), 'udl.config.ts');
+      mockExistsSync.mockImplementation((path) => path === tsConfigPath);
+
+      const unregisterMock = vi.fn();
+      vi.doMock('tsx/esm/api', () => ({
+        register: () => unregisterMock,
+      }));
+
+      const fileUrl = pathToFileURL(tsConfigPath).href;
+      vi.doMock(fileUrl, () => {
+        throw new Error('Config parse error');
+      });
+
+      const { loadPortFromConfig: loadFn } = await import('@/utils/config');
+      await loadFn();
+      expect(unregisterMock).toHaveBeenCalled();
+    });
+  });
+
+  describe('resolveUdlPort', () => {
+    beforeEach(() => {
+      vi.resetModules();
+    });
+
+    afterEach(() => {
+      vi.restoreAllMocks();
+    });
+
+    it('returns CLI port when provided', async () => {
+      const port = await resolveUdlPort(5555);
+      expect(port).toBe(5555);
+    });
+
+    it('returns config port when CLI port not provided', async () => {
+      const mockExistsSync = existsSync as ReturnType<typeof vi.fn>;
+      const jsConfigPath = join(process.cwd(), 'udl.config.js');
+      mockExistsSync.mockImplementation((path) => path === jsConfigPath);
+
+      const fileUrl = pathToFileURL(jsConfigPath).href;
+      vi.doMock(fileUrl, () => ({
+        config: { port: 6666 },
+      }));
+
+      const { resolveUdlPort: resolveFn } = await import('@/utils/config');
+      const port = await resolveFn();
+      expect(port).toBe(6666);
+    });
+
+    it('returns default port when neither CLI nor config port provided', async () => {
+      const mockExistsSync = existsSync as ReturnType<typeof vi.fn>;
+      mockExistsSync.mockReturnValue(false);
+
+      const { resolveUdlPort: resolveFn } = await import('@/utils/config');
+      const port = await resolveFn();
+      expect(port).toBe(4000);
+    });
+
+    it('returns CLI port even when config has port', async () => {
+      const mockExistsSync = existsSync as ReturnType<typeof vi.fn>;
+      const jsConfigPath = join(process.cwd(), 'udl.config.js');
+      mockExistsSync.mockImplementation((path) => path === jsConfigPath);
+
+      const fileUrl = pathToFileURL(jsConfigPath).href;
+      vi.doMock(fileUrl, () => ({
+        config: { port: 6666 },
+      }));
+
+      // CLI port takes priority, so config should not be loaded
+      const port = await resolveUdlPort(7777);
+      expect(port).toBe(7777);
+    });
+  });
+});
diff --git a/packages/core/tests/integration/loader.test.ts b/packages/core/tests/integration/loader.test.ts
index 4cfa42c..dde6179 100644
--- a/packages/core/tests/integration/loader.test.ts
+++ b/packages/core/tests/integration/loader.test.ts
@@ -788,6 +788,102 @@ describe('loader integration tests', () => {
       expect(registeredTypes[0]).toEqual({ name: 'TestType', fields: [] });
     });
 
+    it('should execute sourceNodes hook in loadConfigFile when pluginName and store are provided', async () => {
+      const { NodeStore } = await import('@/nodes/index.js');
+
+      const configPath = join(testDir, 'source-nodes-config.js');
+
+      writeFileSync(
+        configPath,
+        `
+        export const config = {
+          name: 'source-nodes-test'
+        };
+
+        export async function sourceNodes({ actions, createNodeId, options }) {
+          await actions.createNode({
+            internal: {
+              id: createNodeId('SourceNodesTestNode', '1'),
+              type: 'SourceNodesTestNode',
+            },
+            parent: undefined,
+            children: undefined,
+            testOption: options?.testValue || 'default',
+          });
+        }
+        `
+      );
+
+      const store = new NodeStore();
+
+      await loadConfigFile(configPath, {
+        pluginName: 'source-nodes-test-plugin',
+        store,
+        context: {
+          options: { testValue: 'custom-value' },
+        },
+      });
+
+      // Verify the node was created
+      const nodes = store.getAll();
+      expect(nodes).toHaveLength(1);
+      expect(nodes[0]?.internal.type).toBe('SourceNodesTestNode');
+      expect(nodes[0]?.internal.owner).toBe('source-nodes-test-plugin');
+      expect(
+        (nodes[0] as unknown as Record<string, unknown>)['testOption']
+      ).toBe('custom-value');
+    });
+
+    it('should load TypeScript plugin config using tsx loader', async () => {
+      const pluginDir = join(pluginsDir, 'ts-source-plugin');
+      mkdirSync(pluginDir, { recursive: true });
+
+      // Create a TypeScript config (without compiled dist version to force tsx usage)
+      writeFileSync(
+        join(pluginDir, 'udl.config.ts'),
+        `
+        export const config = {
+          name: 'ts-source-plugin'
+        };
+
+        export async function sourceNodes({ actions, createNodeId }) {
+          await actions.createNode({
+            internal: {
+              id: createNodeId('TsPluginNode', '1'),
+              type: 'TsPluginNode',
+            },
+            parent: undefined,
+            children: undefined,
+            fromTs: true,
+          });
+        }
+        `
+      );
+
+      const { NodeStore } = await import('@/nodes/index.js');
+      const store = new NodeStore();
+
+      const consoleLogSpy = vi
+        .spyOn(console, 'log')
+        .mockImplementation(() => {});
+
+      await loadPlugins([pluginDir], {
+        appConfig: {},
+        store,
+        cache: false,
+      });
+
+      // Verify the node was created
+      const nodes = store.getAll();
+      expect(nodes).toHaveLength(1);
+      expect(nodes[0]?.internal.type).toBe('TsPluginNode');
+      expect((nodes[0] as unknown as Record<string, unknown>)['fromTs']).toBe(
+        true
+      );
+
+      consoleLogSpy.mockRestore();
+    });
+
     it('should register reference resolver from plugin config', async () => {
       const { defaultRegistry } = await import('@/references/index.js');
 
@@ -1531,6 +1627,161 @@ describe('loader integration tests', () => {
       // Cleanup
       delete global.__childCacheDir;
     });
+
+    it('should use plugin folder basename as name when config.name is missing', async () => {
+      const pluginDir = join(pluginsDir, 'no-name-plugin-folder');
+      mkdirSync(pluginDir, { recursive: true });
+
+      writeFileSync(
+        join(pluginDir, 'udl.config.js'),
+        `
+        // Config without a name property - should fallback to directory name
+        export const config = {
+          type: 'source'
+        };
+
+        export async function sourceNodes({ actions, createNodeId }) {
+          await actions.createNode({
+            internal: {
+              id: createNodeId('NoNameNode', '1'),
+              type: 'NoNameNode',
+            },
+            parent: undefined,
+            children: undefined,
+          });
+        }
+        `
+      );
+
+      const { NodeStore } = await import('@/nodes/index.js');
+      const consoleLogSpy = vi
+        .spyOn(console, 'log')
+        .mockImplementation(() => {});
+
+      const store = new NodeStore();
+      await loadPlugins([pluginDir], {
+        appConfig: {},
+        store,
+        cache: false,
+      });
+
+      // Verify the node was created with owner being the folder basename
+      const nodes = store.getAll();
+      expect(nodes).toHaveLength(1);
+      expect(nodes[0]?.internal.owner).toBe('no-name-plugin-folder');
+
+      consoleLogSpy.mockRestore();
+    });
+
+    it('should use custom CacheStorage when plugin config provides one', async () => {
+      const pluginDir = join(pluginsDir, 'custom-cache-plugin');
+      mkdirSync(pluginDir, { recursive: true });
+
+      // We'll test by providing a config that has cache as an object (custom CacheStorage)
+      // The test verifies the branch is executed by checking the plugin still works
+      writeFileSync(
+        join(pluginDir, 'udl.config.js'),
+        `
+        // Custom cache storage object
+        const customCacheStorage = {
+          async load() { return null; },
+          async save(data) { /* no-op */ },
+          async clear() { /* no-op */ },
+        };
+
+        export const config = {
+          name: 'custom-cache-plugin',
+          cache: customCacheStorage // Custom CacheStorage object
+        };
+
+        export async function sourceNodes({ actions, createNodeId }) {
+          await actions.createNode({
+            internal: {
+              id: createNodeId('CustomCacheNode', '1'),
+              type: 'CustomCacheNode',
+            },
+            parent: undefined,
+            children: undefined,
+          });
+        }
+        `
+      );
+
+      const { NodeStore } = await import('@/nodes/index.js');
+      const consoleLogSpy = vi
+        .spyOn(console, 'log')
+        .mockImplementation(() => {});
+
+      const store = new NodeStore();
+      await loadPlugins([pluginDir], {
+        appConfig: {},
+        store,
+        cache: true, // Enable caching
+        cacheDir: pluginDir,
+      });
+
+      // Verify the node was created (custom cache was used, doesn't throw)
+      expect(store.getAll()).toHaveLength(1);
+
+      consoleLogSpy.mockRestore();
+    });
+
+    it('should handle plugin options without indexes property', async () => {
+      const pluginDir = join(pluginsDir, 'no-indexes-options-plugin');
+      mkdirSync(pluginDir, { recursive: true });
+
+      writeFileSync(
+        join(pluginDir, 'udl.config.js'),
+        `
+        export const config = {
+          name: 'no-indexes-options-plugin'
+        };
+
+        export async function sourceNodes({ actions, createNodeId, options }) {
+          await actions.createNode({
+            internal: {
+              id: createNodeId('NoIndexesNode', '1'),
+              type: 'NoIndexesNode',
+            },
+            parent: undefined,
+            children: undefined,
+            optionValue: options?.someOption || 'default',
+          });
+        }
+        `
+      );
+
+      const { NodeStore } = await import('@/nodes/index.js');
+      const consoleLogSpy = vi
+        .spyOn(console, 'log')
+        .mockImplementation(() => {});
+
+      const store = new NodeStore();
+
+      // Pass plugin options WITHOUT indexes property
+      await loadPlugins(
+        [
+          {
+            name: pluginDir,
+            options: { someOption: 'custom-value' }, // No indexes here
+          },
+        ],
+        {
+          appConfig: {},
+          store,
+          cache: false,
+        }
+      );
+
+      // Verify the node was created
+      const nodes = store.getAll();
+      expect(nodes).toHaveLength(1);
+      expect(
+        (nodes[0] as unknown as Record<string, unknown>)['optionValue']
+      ).toBe('custom-value');
+
+      consoleLogSpy.mockRestore();
+    });
   });
 
   describe('loadPlugins webhook and idField handling', () => {
diff --git a/packages/core/tests/unit/cache/manager.test.ts b/packages/core/tests/unit/cache/manager.test.ts
new file mode 100644
index 0000000..9dfa5c0
--- /dev/null
+++ b/packages/core/tests/unit/cache/manager.test.ts
@@ -0,0 +1,384 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import {
+  setStore,
+  getStore,
+  registerPluginCache,
+  initPluginCache,
+  hasPluginCache,
+  getPluginCache,
+  getRegisteredPlugins,
+  savePluginCache,
+  saveAffectedPlugins,
+  replaceAllCaches,
+  clearAllCaches,
+  resetCacheManager,
+} from '@/cache/manager.js';
+import type { CacheStorage, CachedData } from '@/cache/types.js';
+import { FileCacheStorage } from '@/cache/file-cache.js';
+import { NodeStore } from '@/nodes/store.js';
+import type { Node } from '@/nodes/types.js';
+
+/** Helper to create a valid test node */
+function createTestNode(
+  overrides: Partial<Node> & {
+    id?: string;
+    _type?: string;
+    _owner?: string;
+  } = {}
+): Node {
+  const {
+    id = 'node-1',
+    _type = 'TestNode',
+    _owner = 'test-plugin',
+    ...rest
+  } = overrides;
+  return {
+    internal: {
+      id,
+      type: _type,
+      contentDigest: 'test-digest',
+      owner: _owner,
+      createdAt: 1000,
+      modifiedAt: 2000,
+    },
+    ...rest,
+  };
+}
+
+/** Create a mock CacheStorage */
+function createMockCache(): CacheStorage & {
+  savedData: CachedData | null;
+  loadedData: CachedData | null;
+} {
+  return {
+    savedData: null,
+    loadedData: null,
+    async load() {
+      return this.loadedData;
+    },
+    async save(data: CachedData) {
+      this.savedData = data;
+    },
+    async clear() {
+      this.savedData = null;
+    },
+  };
+}
+
+describe('Cache Manager', () => {
+  let store: NodeStore;
+
+  beforeEach(() => {
+    resetCacheManager();
+    store = new NodeStore();
+    vi.spyOn(console, 'log').mockImplementation(() => {});
+    vi.spyOn(console, 'warn').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe('store management', () => {
+    it('should set and get store reference', () => {
+      expect(getStore()).toBeNull();
+      setStore(store);
+      expect(getStore()).toBe(store);
+    });
+  });
+
+  describe('registerPluginCache', () => {
+    it('should register a plugin cache', () => {
+      const cache = createMockCache();
+      registerPluginCache('plugin-a', cache);
+
+      expect(hasPluginCache('plugin-a')).toBe(true);
+      expect(getPluginCache('plugin-a')).toBe(cache);
+    });
+
+    it('should return false for unregistered plugin', () => {
+      expect(hasPluginCache('nonexistent')).toBe(false);
+      expect(getPluginCache('nonexistent')).toBeUndefined();
+    });
+
+    it('should track all registered plugins', () => {
+      const cacheA = createMockCache();
+      const cacheB = createMockCache();
+
+      registerPluginCache('plugin-a', cacheA);
+      registerPluginCache('plugin-b', cacheB);
+
+      const plugins = getRegisteredPlugins();
+      expect(plugins).toContain('plugin-a');
+      expect(plugins).toContain('plugin-b');
+      expect(plugins).toHaveLength(2);
+    });
+  });
+
+  describe('initPluginCache', () => {
+    it('should create FileCacheStorage by default and register it', () => {
+      const cache = initPluginCache('plugin-a', '/path/to/cache');
+
+      expect(cache).toBeInstanceOf(FileCacheStorage);
+      expect(hasPluginCache('plugin-a')).toBe(true);
+      expect(getPluginCache('plugin-a')).toBe(cache);
+    });
+
+    it('should use custom cache when provided', () => {
+      const customCache = createMockCache();
+      const cache = initPluginCache('plugin-a', '/path/to/cache', customCache);
+
+      expect(cache).toBe(customCache);
+      expect(hasPluginCache('plugin-a')).toBe(true);
+      expect(getPluginCache('plugin-a')).toBe(customCache);
+    });
+
+    it('should return the cache for later use', () => {
+      const cache = initPluginCache('plugin-a', '/some/path');
+
+      // Should be able to use the returned cache directly
+      expect(cache).toBeDefined();
+      expect(typeof cache.save).toBe('function');
+      expect(typeof cache.load).toBe('function');
+      expect(typeof cache.clear).toBe('function');
+    });
+  });
+
+  describe('savePluginCache', () => {
+    it('should save nodes owned by the plugin', async () => {
+      const cache = createMockCache();
+      registerPluginCache('plugin-a', cache);
+      setStore(store);
+
+      // Add nodes to store
+      store.set(createTestNode({ id: 'node-1', _owner: 'plugin-a' }));
+      store.set(createTestNode({ id: 'node-2', _owner: 'plugin-a' }));
+      store.set(createTestNode({ id: 'node-3', _owner: 'plugin-b' }));
+
+      const result = await savePluginCache('plugin-a');
+
+      expect(result).toBe(true);
+      expect(cache.savedData).not.toBeNull();
+      expect(cache.savedData?.nodes).toHaveLength(2);
+      expect(cache.savedData?.nodes.map((n) => n.internal.id)).toContain(
+        'node-1'
+      );
+      expect(cache.savedData?.nodes.map((n) => n.internal.id)).toContain(
+        'node-2'
+      );
+    });
+
+    it('should include indexes for plugin node types', async () => {
+      const cache = createMockCache();
+      registerPluginCache('plugin-a', cache);
+      setStore(store);
+
+      // Add nodes and register indexes
+      store.set(
+        createTestNode({ id: 'node-1', _type: 'Product', _owner: 'plugin-a' })
+      );
+      store.registerIndex('Product', 'slug');
+
+      await savePluginCache('plugin-a');
+
+      expect(cache.savedData?.indexes).toEqual({ Product: ['slug'] });
+    });
+
+    it('should return false for unregistered plugin', async () => {
+      setStore(store);
+      const result = await savePluginCache('nonexistent');
+      expect(result).toBe(false);
+    });
+
+    it('should return false when no store is available', async () => {
+      const cache = createMockCache();
+      registerPluginCache('plugin-a', cache);
+
+      const result = await savePluginCache('plugin-a');
+      expect(result).toBe(false);
+    });
+
+    it('should use provided store over registered store', async () => {
+      const cache = createMockCache();
+      const alternateStore = new NodeStore();
+
+      registerPluginCache('plugin-a', cache);
+      setStore(store);
+
+      // Add different nodes to each store
+      store.set(createTestNode({ id: 'node-1', _owner: 'plugin-a' }));
+      alternateStore.set(
+        createTestNode({ id: 'alt-node-1', _owner: 'plugin-a' })
+      );
+
+      await savePluginCache('plugin-a', alternateStore);
+
+      expect(cache.savedData?.nodes).toHaveLength(1);
+      expect(cache.savedData?.nodes[0]?.internal.id).toBe('alt-node-1');
+    });
+  });
+
+  describe('saveAffectedPlugins', () => {
+    it('should save caches for all affected plugins', async () => {
+      const cacheA = createMockCache();
+      const cacheB = createMockCache();
+
+      registerPluginCache('plugin-a', cacheA);
+      registerPluginCache('plugin-b', cacheB);
+      setStore(store);
+
+      store.set(createTestNode({ id: 'node-1', _owner: 'plugin-a' }));
+      store.set(createTestNode({ id: 'node-2', _owner: 'plugin-b' }));
+
+      await saveAffectedPlugins(new Set(['plugin-a', 'plugin-b']));
+
+      expect(cacheA.savedData?.nodes).toHaveLength(1);
+      expect(cacheB.savedData?.nodes).toHaveLength(1);
+    });
+
+    it('should skip plugins without registered caches', async () => {
+      const cacheA = createMockCache();
+      registerPluginCache('plugin-a', cacheA);
+      setStore(store);
+
+      store.set(createTestNode({ id: 'node-1', _owner: 'plugin-a' }));
+      store.set(createTestNode({ id: 'node-2', _owner: 'plugin-b' }));
+
+      // plugin-b is not registered
+      await saveAffectedPlugins(new Set(['plugin-a', 'plugin-b']));
+
+      expect(cacheA.savedData?.nodes).toHaveLength(1);
+    });
+  });
+
+  describe('replaceAllCaches', () => {
+    it('should save all nodes grouped by owner', async () => {
+      const cacheA = createMockCache();
+      const cacheB = createMockCache();
+
+      registerPluginCache('plugin-a', cacheA);
+      registerPluginCache('plugin-b', cacheB);
+      setStore(store);
+
+      store.set(createTestNode({ id: 'node-1', _owner: 'plugin-a' }));
+      store.set(createTestNode({ id: 'node-2', _owner: 'plugin-a' }));
+      store.set(createTestNode({ id: 'node-3', _owner: 'plugin-b' }));
+
+      await replaceAllCaches();
+
+      expect(cacheA.savedData?.nodes).toHaveLength(2);
+      expect(cacheB.savedData?.nodes).toHaveLength(1);
+    });
+
+    it('should skip plugins without registered caches', async () => {
+      const cacheA = createMockCache();
+      registerPluginCache('plugin-a', cacheA);
+      setStore(store);
+
+      store.set(createTestNode({ id: 'node-1', _owner: 'plugin-a' }));
+      store.set(createTestNode({ id: 'node-2', _owner: 'plugin-b' }));
+
+      // plugin-b is not registered - should not throw
+      await replaceAllCaches();
+
+      expect(cacheA.savedData?.nodes).toHaveLength(1);
+    });
+
+    it('should handle empty store', async () => {
+      const cacheA = createMockCache();
+      registerPluginCache('plugin-a', cacheA);
+      setStore(store);
+
+      await replaceAllCaches();
+
+      // Should complete without error, no nodes to save
+      expect(cacheA.savedData).toBeNull();
+    });
+
+    it('should warn and return early when no store is available', async () => {
+      const cacheA = createMockCache();
+      registerPluginCache('plugin-a', cacheA);
+      // No store is set and no store is passed
+
+      await replaceAllCaches();
+
+      // Should warn and not save anything
+      expect(console.warn).toHaveBeenCalledWith(
+        '⚠️ [CacheManager] No store available for replacing all caches'
+      );
+      expect(cacheA.savedData).toBeNull();
+    });
+
+    it('should include indexes for node types in replaceAllCaches', async () => {
+      const cacheA = createMockCache();
+      registerPluginCache('plugin-a', cacheA);
+      setStore(store);
+
+      // Add node and register indexes
+      store.set(
+        createTestNode({ id: 'node-1', _type: 'Product', _owner: 'plugin-a' })
+      );
+      store.registerIndex('Product', 'slug');
+
+      await replaceAllCaches();
+
+      expect(cacheA.savedData?.indexes).toEqual({ Product: ['slug'] });
+    });
+
+    it('should use provided store over registered store', async () => {
+      const cacheA = createMockCache();
+      const alternateStore = new NodeStore();
+
+      registerPluginCache('plugin-a', cacheA);
+      setStore(store);
+
+      alternateStore.set(
+        createTestNode({ id: 'alt-node-1', _owner: 'plugin-a' })
+      );
+
+      await replaceAllCaches(alternateStore);
+
+      expect(cacheA.savedData?.nodes).toHaveLength(1);
+      expect(cacheA.savedData?.nodes[0]?.internal.id).toBe('alt-node-1');
+    });
+  });
+
+  describe('clearAllCaches', () => {
+    it('should clear all registered caches', async () => {
+      const cacheA = createMockCache();
+      const cacheB = createMockCache();
+
+      cacheA.savedData = {
+        nodes: [],
+        indexes: {},
+        meta: { version: 1, createdAt: 0, updatedAt: 0 },
+      };
+      cacheB.savedData = {
+        nodes: [],
+        indexes: {},
+        meta: { version: 1, createdAt: 0, updatedAt: 0 },
+      };
+
+      registerPluginCache('plugin-a', cacheA);
+      registerPluginCache('plugin-b', cacheB);
+
+      await clearAllCaches();
+
+      expect(cacheA.savedData).toBeNull();
+      expect(cacheB.savedData).toBeNull();
+    });
+  });
+
+  describe('resetCacheManager', () => {
+    it('should reset all state', () => {
+      const cache = createMockCache();
+      registerPluginCache('plugin-a', cache);
+      setStore(store);
+
+      resetCacheManager();
+
+      expect(getRegisteredPlugins()).toHaveLength(0);
+      expect(getStore()).toBeNull();
+    });
+  });
+});
diff --git a/packages/core/tests/unit/config.test.ts b/packages/core/tests/unit/config.test.ts
index 8b74c7e..abdbd99 100644
--- a/packages/core/tests/unit/config.test.ts
+++ b/packages/core/tests/unit/config.test.ts
@@ -1,15 +1,23 @@
-import { afterEach, describe, expect, it } from 'vitest';
-import { createConfig, getConfig } from '@/config.js';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import {
+  createConfig,
+  getConfig,
+  resetConfig,
+  isConfigInitialized,
+  UDL_ENDPOINT_ENV,
+} from '@/config.js';
 
 describe('config', () => {
+  beforeEach(() => {
+    // Reset config state before each test
+    resetConfig();
+    // Clear the env var
+    delete process.env[UDL_ENDPOINT_ENV];
+  });
+
   afterEach(() => {
-    // Reset to default config after each test
-    createConfig({
-      staticPath: '/static/',
-      endpoint: 'http://localhost:4000/graphql',
-      port: 4000,
-      host: 'localhost',
-    });
+    // Clean up env var
+    delete process.env[UDL_ENDPOINT_ENV];
   });
 
   describe('createConfig', () => {
@@ -169,4 +177,63 @@ describe('config', () => {
       expect(config2.endpoint).toBe('http://localhost:4000/graphql');
     });
   });
+
+  describe('UDL_ENDPOINT environment variable', () => {
+    it('should use UDL_ENDPOINT env var when config is not initialized', () => {
+      process.env[UDL_ENDPOINT_ENV] = 'http://localhost:5000/graphql';
+
+      const config = getConfig();
+
+      expect(config.endpoint).toBe('http://localhost:5000/graphql');
+    });
+
+    it('should ignore UDL_ENDPOINT env var when config is explicitly initialized', () => {
+      process.env[UDL_ENDPOINT_ENV] = 'http://localhost:5000/graphql';
+
+      // Explicitly initialize config
+      createConfig({ port: 4001 });
+
+      const config = getConfig();
+
+      expect(config.endpoint).toBe('http://localhost:4001/graphql');
+    });
+
+    it('should return default endpoint when env var is not set and config not initialized', () => {
+      const config = getConfig();
+
+      expect(config.endpoint).toBe('http://localhost:4000/graphql');
+    });
+  });
+
+  describe('isConfigInitialized', () => {
+    it('should return false before createConfig is called', () => {
+      expect(isConfigInitialized()).toBe(false);
+    });
+
+    it('should return true after createConfig is called', () => {
+      createConfig({ port: 5000 });
+
+      expect(isConfigInitialized()).toBe(true);
+    });
+
+    it('should return false after resetConfig is called', () => {
+      createConfig({ port: 5000 });
+      resetConfig();
+
+      expect(isConfigInitialized()).toBe(false);
+    });
+  });
+
+  describe('resetConfig', () => {
+    it('should reset config to default values', () => {
+      createConfig({ port: 5000, host: 'custom.host' });
+      resetConfig();
+
+      const config = getConfig();
+
+      expect(config.port).toBe(4000);
+      expect(config.host).toBe('localhost');
+      expect(config.endpoint).toBe('http://localhost:4000/graphql');
+    });
+  });
 });
diff --git a/packages/core/tests/unit/sync/remote.test.ts b/packages/core/tests/unit/sync/remote.test.ts
index c8c2709..440dd9c 100644
--- a/packages/core/tests/unit/sync/remote.test.ts
+++ b/packages/core/tests/unit/sync/remote.test.ts
@@ -17,6 +17,11 @@ vi.mock('@/websocket/client.js', () => ({
   UDLWebSocketClient: vi.fn(),
 }));
 
+// Mock cache manager functions to avoid store.getAll() issues
+vi.mock('@/cache/manager.js', () => ({
+  replaceAllCaches: vi.fn().mockResolvedValue(undefined),
+}));
+
 // Mock console.log to avoid noise in tests
 vi.spyOn(console, 'log').mockImplementation(() => {});
 
@@ -236,6 +241,52 @@ describe('remote sync', () => {
         maxReconnectAttempts: 3,
       });
     });
+
+    it('passes onWebhookReceived callback to WebSocket client', async () => {
+      const mockConnect = vi.fn().mockResolvedValue(undefined);
+      const mockClientInstance = { connect: mockConnect };
+
+      vi.mocked(UDLWebSocketClient).mockImplementation(
+        () => mockClientInstance as unknown as UDLWebSocketClient
+      );
+
+      const mockStore = {} as NodeStore;
+      const onWebhookReceived = vi.fn();
+
+      await tryConnectRemoteWebSocket(
+        'http://localhost:4000',
+        mockStore,
+        undefined,
+        onWebhookReceived
+      );
+
+      expect(UDLWebSocketClient).toHaveBeenCalledWith({
+        url: 'ws://localhost:4000/ws',
+        onWebhookReceived,
+      });
+    });
+
+    it('does not include onWebhookReceived when not provided', async () => {
+      const mockConnect = vi.fn().mockResolvedValue(undefined);
+      const mockClientInstance = { connect: mockConnect };
+
+      vi.mocked(UDLWebSocketClient).mockImplementation(
+        () => mockClientInstance as unknown as UDLWebSocketClient
+      );
+
+      const mockStore = {} as NodeStore;
+
+      await tryConnectRemoteWebSocket(
+        'http://localhost:4000',
+        mockStore,
+        undefined,
+        undefined
+      );
+
+      expect(UDLWebSocketClient).toHaveBeenCalledWith({
+        url: 'ws://localhost:4000/ws',
+      });
+    });
   });
 
   describe('initRemoteSync', () => {
@@ -326,5 +377,111 @@ describe('remote sync', () => {
         reconnectDelayMs: 3000,
       });
     });
+
+    it('logs instant webhook relay when wsClient and onWebhookReceived are both present', async () => {
+      // Mock fetchRemoteNodes
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ updated: [], deleted: [] }),
+      });
+
+      // Mock WebSocket connection success
+      const mockConnect = vi.fn().mockResolvedValue(undefined);
+      const mockClientInstance = { connect: mockConnect };
+      vi.mocked(UDLWebSocketClient).mockImplementation(
+        () => mockClientInstance as unknown as UDLWebSocketClient
+      );
+
+      const mockStore = {
+        set: vi.fn(),
+      } as unknown as NodeStore;
+
+      const onWebhookReceived = vi.fn();
+      const consoleLogSpy = vi.spyOn(console, 'log');
+
+      await initRemoteSync(
+        {
+          url: 'http://localhost:4000',
+          onWebhookReceived,
+        },
+        mockStore
+      );
+
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        '📡 Instant webhook relay enabled for local processing'
+      );
+    });
+
+    it('does not log instant webhook relay when wsClient is null', async () => {
+      // Mock fetchRemoteNodes
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ updated: [], deleted: [] }),
+      });
+
+      // Mock WebSocket connection failure
+      const mockConnect = vi
+        .fn()
+        .mockRejectedValue(new Error('Connection failed'));
+      const mockClientInstance = { connect: mockConnect };
+      vi.mocked(UDLWebSocketClient).mockImplementation(
+        () => mockClientInstance as unknown as UDLWebSocketClient
+      );
+
+      const mockStore = {
+        set: vi.fn(),
+      } as unknown as NodeStore;
+
+      const onWebhookReceived = vi.fn();
+      const consoleLogSpy = vi.spyOn(console, 'log');
+      consoleLogSpy.mockClear();
+
+      await initRemoteSync(
+        {
+          url: 'http://localhost:4000',
+          onWebhookReceived,
+        },
+        mockStore
+      );
+
+      // Should not log the instant webhook relay message
+      expect(consoleLogSpy).not.toHaveBeenCalledWith(
+        '📡 Instant webhook relay enabled for local processing'
+      );
+    });
+
+    it('does not log instant webhook relay when onWebhookReceived is not provided', async () => {
+      // Mock fetchRemoteNodes
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ updated: [], deleted: [] }),
+      });
+
+      // Mock WebSocket connection success
+      const mockConnect = vi.fn().mockResolvedValue(undefined);
+      const mockClientInstance = { connect: mockConnect };
+      vi.mocked(UDLWebSocketClient).mockImplementation(
+        () => mockClientInstance as unknown as UDLWebSocketClient
+      );
+
+      const mockStore = {
+        set: vi.fn(),
+      } as unknown as NodeStore;
+
+      const consoleLogSpy = vi.spyOn(console, 'log');
+      consoleLogSpy.mockClear();
+
+      await initRemoteSync(
+        {
+          url: 'http://localhost:4000',
+        },
+        mockStore
+      );
+
+      // Should not log the instant webhook relay message
+      expect(consoleLogSpy).not.toHaveBeenCalledWith(
+        '📡 Instant webhook relay enabled for local processing'
+      );
+    });
   });
 });
diff --git a/packages/core/tests/unit/webhooks/queue.test.ts b/packages/core/tests/unit/webhooks/queue.test.ts
index 0f213c9..bdf4a21 100644
--- a/packages/core/tests/unit/webhooks/queue.test.ts
+++ b/packages/core/tests/unit/webhooks/queue.test.ts
@@ -7,14 +7,9 @@ import {
 } from '@/webhooks/index.js';
 
 // Helper to create a mock webhook
-function createMockWebhook(
-  pluginName: string,
-  path: string,
-  body?: unknown
-): QueuedWebhook {
+function createMockWebhook(pluginName: string, body?: unknown): QueuedWebhook {
   return {
     pluginName,
-    path,
     rawBody: Buffer.from(JSON.stringify(body ?? {})),
     body: body ?? {},
     headers: { 'content-type': 'application/json' },
@@ -64,20 +59,41 @@ describe('WebhookQueue', () => {
 
   describe('enqueue', () => {
     it('should add webhook to queue', () => {
-      const webhook = createMockWebhook('plugin', 'path');
+      const webhook = createMockWebhook('plugin');
       queue.enqueue(webhook);
       expect(queue.size()).toBe(1);
     });
 
+    it('should emit webhook:queued immediately on enqueue', () => {
+      const queuedWebhooks: QueuedWebhook[] = [];
+      queue.on('webhook:queued', (webhook: QueuedWebhook) => {
+        queuedWebhooks.push(webhook);
+      });
+
+      const webhook1 = createMockWebhook('plugin', { id: 1 });
+      const webhook2 = createMockWebhook('plugin', { id: 2 });
+
+      queue.enqueue(webhook1);
+      expect(queuedWebhooks.length).toBe(1);
+      expect(queuedWebhooks[0]).toBe(webhook1);
+
+      queue.enqueue(webhook2);
+      expect(queuedWebhooks.length).toBe(2);
+      expect(queuedWebhooks[1]).toBe(webhook2);
+
+      // Events should fire immediately, not waiting for debounce
+      expect(queue.size()).toBe(2); // Webhooks still in queue
+    });
+
     it('should increment queue size with each enqueue', () => {
-      queue.enqueue(createMockWebhook('plugin', 'path-1'));
-      queue.enqueue(createMockWebhook('plugin', 'path-2'));
-      queue.enqueue(createMockWebhook('plugin', 'path-3'));
+      queue.enqueue(createMockWebhook('plugin'));
+      queue.enqueue(createMockWebhook('plugin'));
+      queue.enqueue(createMockWebhook('plugin'));
       expect(queue.size()).toBe(3);
     });
 
     it('should start debounce timer on first enqueue', () => {
-      const webhook = createMockWebhook('plugin', 'path');
+      const webhook = createMockWebhook('plugin');
       queue.enqueue(webhook);
 
       // Queue should not be processed yet
@@ -93,14 +109,14 @@ describe('WebhookQueue', () => {
     });
 
     it('should reset debounce timer on each enqueue', () => {
-      queue.enqueue(createMockWebhook('plugin', 'path-1'));
+      queue.enqueue(createMockWebhook('plugin'));
 
       // Advance timer by 4000ms
       vi.advanceTimersByTime(4000);
       expect(queue.size()).toBe(1);
 
       // Enqueue another webhook - should reset timer
-      queue.enqueue(createMockWebhook('plugin', 'path-2'));
+      queue.enqueue(createMockWebhook('plugin'));
 
       // Advance timer by 4000ms again (total 8000ms since first enqueue)
       vi.advanceTimersByTime(4000);
@@ -119,16 +135,16 @@ describe('WebhookQueue', () => {
         processedWebhooks.push(webhook);
       });
 
-      queue.enqueue(createMockWebhook('plugin', 'path-1'));
-      queue.enqueue(createMockWebhook('plugin', 'path-2'));
-      queue.enqueue(createMockWebhook('plugin', 'path-3'));
+      queue.enqueue(createMockWebhook('plugin', { id: 1 }));
+      queue.enqueue(createMockWebhook('plugin', { id: 2 }));
+      queue.enqueue(createMockWebhook('plugin', { id: 3 }));
 
       vi.advanceTimersByTime(5000);
 
       expect(processedWebhooks.length).toBe(3);
-      expect(processedWebhooks[0]?.path).toBe('path-1');
-      expect(processedWebhooks[1]?.path).toBe('path-2');
-      expect(processedWebhooks[2]?.path).toBe('path-3');
+      expect((processedWebhooks[0]?.body as { id: number }).id).toBe(1);
+      expect((processedWebhooks[1]?.body as { id: number }).id).toBe(2);
+      expect((processedWebhooks[2]?.body as { id: number }).id).toBe(3);
     });
 
     it('should emit webhook:batch-complete after processing', async () => {
@@ -137,8 +153,8 @@ describe('WebhookQueue', () => {
         completedBatch = batch;
       });
 
-      queue.enqueue(createMockWebhook('plugin', 'path-1'));
-      queue.enqueue(createMockWebhook('plugin', 'path-2'));
+      queue.enqueue(createMockWebhook('plugin'));
+      queue.enqueue(createMockWebhook('plugin'));
 
       vi.advanceTimersByTime(5000);
 
@@ -158,7 +174,7 @@ describe('WebhookQueue', () => {
 
       // Enqueue 10 webhooks rapidly
       for (let i = 0; i < 10; i++) {
-        queue.enqueue(createMockWebhook('plugin', `path-${i}`));
+        queue.enqueue(createMockWebhook('plugin'));
       }
 
       vi.advanceTimersByTime(5000);
@@ -180,7 +196,7 @@ describe('WebhookQueue', () => {
 
       // Enqueue 5 webhooks (max size)
       for (let i = 0; i < 5; i++) {
-        smallQueue.enqueue(createMockWebhook('plugin', `path-${i}`));
+        smallQueue.enqueue(createMockWebhook('plugin'));
       }
 
       // Should process immediately without waiting for debounce
@@ -191,8 +207,8 @@ describe('WebhookQueue', () => {
 
   describe('flush', () => {
     it('should process queued webhooks immediately', async () => {
-      queue.enqueue(createMockWebhook('plugin', 'path-1'));
-      queue.enqueue(createMockWebhook('plugin', 'path-2'));
+      queue.enqueue(createMockWebhook('plugin'));
+      queue.enqueue(createMockWebhook('plugin'));
 
       expect(queue.size()).toBe(2);
 
@@ -202,7 +218,7 @@ describe('WebhookQueue', () => {
     });
 
     it('should clear debounce timer', async () => {
-      queue.enqueue(createMockWebhook('plugin', 'path-1'));
+      queue.enqueue(createMockWebhook('plugin'));
 
       // Advance timer partially
       vi.advanceTimersByTime(2000);
@@ -222,7 +238,7 @@ describe('WebhookQueue', () => {
         completed = true;
       });
 
-      queue.enqueue(createMockWebhook('plugin', 'path-1'));
+      queue.enqueue(createMockWebhook('plugin'));
       await queue.flush();
 
       expect(completed).toBe(true);
@@ -242,8 +258,8 @@ describe('WebhookQueue', () => {
 
   describe('clear', () => {
     it('should remove all queued webhooks', () => {
-      queue.enqueue(createMockWebhook('plugin', 'path-1'));
-      queue.enqueue(createMockWebhook('plugin', 'path-2'));
+      queue.enqueue(createMockWebhook('plugin'));
+      queue.enqueue(createMockWebhook('plugin'));
 
       expect(queue.size()).toBe(2);
 
@@ -253,7 +269,7 @@ describe('WebhookQueue', () => {
     });
 
     it('should clear debounce timer', () => {
-      queue.enqueue(createMockWebhook('plugin', 'path-1'));
+      queue.enqueue(createMockWebhook('plugin'));
 
       queue.clear();
 
@@ -271,15 +287,15 @@ describe('WebhookQueue', () => {
     });
 
     it('should return correct count after enqueue', () => {
-      queue.enqueue(createMockWebhook('plugin', 'path-1'));
+      queue.enqueue(createMockWebhook('plugin'));
       expect(queue.size()).toBe(1);
 
-      queue.enqueue(createMockWebhook('plugin', 'path-2'));
+      queue.enqueue(createMockWebhook('plugin'));
       expect(queue.size()).toBe(2);
     });
 
     it('should return 0 after processing', () => {
-      queue.enqueue(createMockWebhook('plugin', 'path-1'));
+      queue.enqueue(createMockWebhook('plugin'));
       vi.advanceTimersByTime(5000);
       expect(queue.size()).toBe(0);
     });
@@ -308,7 +324,7 @@ describe('WebhookQueue', () => {
         },
       });
 
-      slowQueue.enqueue(createMockWebhook('plugin', 'path-1'));
+      slowQueue.enqueue(createMockWebhook('plugin'));
 
       // Trigger processing
       vi.advanceTimersByTime(1000);
@@ -334,8 +350,8 @@ describe('WebhookQueue', () => {
         };
       });
 
-      queue.enqueue(createMockWebhook('plugin', 'path-1'));
-      queue.enqueue(createMockWebhook('plugin', 'path-2'));
+      queue.enqueue(createMockWebhook('plugin'));
+      queue.enqueue(createMockWebhook('plugin'));
 
       await queue.flush();
 
@@ -354,7 +370,7 @@ describe('WebhookQueue', () => {
         completedAt: Date.now(),
       }));
 
-      queue.enqueue(createMockWebhook('plugin', 'path-1'));
+      queue.enqueue(createMockWebhook('plugin'));
       await queue.flush();
 
       // Custom processor handles processing, so no events emitted
@@ -383,7 +399,7 @@ describe('WebhookQueue', () => {
         }
       );
 
-      queue.enqueue(createMockWebhook('plugin', 'path-1'));
+      queue.enqueue(createMockWebhook('plugin'));
       await queue.flush();
 
       expect(receivedError).toBeDefined();
@@ -400,7 +416,7 @@ describe('WebhookQueue', () => {
         throw new Error('Processing failed');
       });
 
-      queue.enqueue(createMockWebhook('plugin', 'path-1'));
+      queue.enqueue(createMockWebhook('plugin'));
       await queue.flush();
 
       expect(queue.processing()).toBe(false);
@@ -424,7 +440,7 @@ describe('WebhookQueue', () => {
         }
       );
 
-      queue.enqueue(createMockWebhook('plugin', 'path-1'));
+      queue.enqueue(createMockWebhook('plugin'));
       await queue.flush();
 
       expect(receivedError).toBeDefined();
diff --git a/packages/core/tests/unit/websocket/client.test.ts b/packages/core/tests/unit/websocket/client.test.ts
index 7796203..7ab295a 100644
--- a/packages/core/tests/unit/websocket/client.test.ts
+++ b/packages/core/tests/unit/websocket/client.test.ts
@@ -2,6 +2,7 @@ import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import WebSocket from 'ws';
 import { UDLWebSocketClient } from '@/websocket/client.js';
 import type { NodeStore } from '@/nodes/store.js';
+import { savePluginCache } from '@/cache/manager.js';
 
 // WebSocket ready state constants
 const WS_OPEN = 1;
@@ -20,6 +21,11 @@ vi.mock('ws', () => {
   };
 });
 
+// Mock the cache manager
+vi.mock('@/cache/manager.js', () => ({
+  savePluginCache: vi.fn().mockResolvedValue(undefined),
+}));
+
 // Helper to create a mock WebSocket instance
 function createMockWs() {
   const handlers: Record<string, ((...args: unknown[]) => void)[]> = {};
@@ -282,6 +288,68 @@ describe('UDLWebSocketClient', () => {
       });
     });
 
+    it('should call savePluginCache when node has owner in internal', async () => {
+      const client = new UDLWebSocketClient({ url: 'ws://localhost:4000/ws' });
+      const store = createMockStore();
+
+      const connectPromise = client.connect(store);
+      mockWs.emit('open');
+      await connectPromise;
+
+      // Clear any previous calls
+      vi.mocked(savePluginCache).mockClear();
+
+      const message = {
+        type: 'node:created',
+        nodeId: 'prod-1',
+        nodeType: 'Product',
+        data: {
+          id: 'prod-1',
+          name: 'Test Product',
+          internal: {
+            id: 'prod-1',
+            type: 'Product',
+            owner: '@universal-data-layer/plugin-source-contentful',
+          },
+        },
+      };
+      mockWs.emit('message', Buffer.from(JSON.stringify(message)));
+
+      expect(savePluginCache).toHaveBeenCalledWith(
+        '@universal-data-layer/plugin-source-contentful'
+      );
+    });
+
+    it('should not call savePluginCache when owner is not a string', async () => {
+      const client = new UDLWebSocketClient({ url: 'ws://localhost:4000/ws' });
+      const store = createMockStore();
+
+      const connectPromise = client.connect(store);
+      mockWs.emit('open');
+      await connectPromise;
+
+      // Clear any previous calls
+      vi.mocked(savePluginCache).mockClear();
+
+      const message = {
+        type: 'node:created',
+        nodeId: 'prod-1',
+        nodeType: 'Product',
+        data: {
+          id: 'prod-1',
+          name: 'Test Product',
+          internal: {
+            id: 'prod-1',
+            type: 'Product',
+            owner: 123, // Not a string
+          },
+        },
+      };
+      mockWs.emit('message', Buffer.from(JSON.stringify(message)));
+
+      expect(savePluginCache).not.toHaveBeenCalled();
+    });
+
     it('should handle node:deleted message', async () => {
       const client = new UDLWebSocketClient({ url: 'ws://localhost:4000/ws' });
       const store = createMockStore();
@@ -303,6 +371,40 @@ describe('UDLWebSocketClient', () => {
       );
     });
 
+    it('should call savePluginCache when deleting node with owner', async () => {
+      const client = new UDLWebSocketClient({ url: 'ws://localhost:4000/ws' });
+      const store = createMockStore();
+
+      // Mock store.get to return a node with an owner
+      vi.mocked(store.get).mockReturnValue({
+        internal: {
+          id: 'prod-1',
+          type: 'Product',
+          owner: '@universal-data-layer/plugin-source-contentful',
+        },
+      } as unknown as import('@/nodes/types.js').Node);
+
+      const connectPromise = client.connect(store);
+      mockWs.emit('open');
+      await connectPromise;
+
+      // Clear any previous calls
+      vi.mocked(savePluginCache).mockClear();
+
+      const message = {
+        type: 'node:deleted',
+        nodeId: 'prod-1',
+        nodeType: 'Product',
+      };
+      mockWs.emit('message', Buffer.from(JSON.stringify(message)));
+
+      expect(store.get).toHaveBeenCalledWith('prod-1');
+      expect(store.delete).toHaveBeenCalledWith('prod-1');
+      expect(savePluginCache).toHaveBeenCalledWith(
+        '@universal-data-layer/plugin-source-contentful'
+      );
+    });
+
     it('should ignore invalid JSON messages', async () => {
       const client = new UDLWebSocketClient({ url: 'ws://localhost:4000/ws' });
       const store = createMockStore();
@@ -321,6 +423,169 @@ describe('UDLWebSocketClient', () => {
       expect(store.delete).not.toHaveBeenCalled();
     });
 
+    it('should handle webhook:received message and call callback', async () => {
+      const onWebhookReceived = vi.fn();
+      const client = new UDLWebSocketClient({
+        url: 'ws://localhost:4000/ws',
+        onWebhookReceived,
+      });
+      const store = createMockStore();
+
+      const connectPromise = client.connect(store);
+      mockWs.emit('open');
+      await connectPromise;
+
+      const message = {
+        type: 'webhook:received',
+        pluginName: 'test-plugin',
+        body: { action: 'update', id: '123' },
+        headers: { 'content-type': 'application/json' },
+        timestamp: '2024-01-01T00:00:00.000Z',
+      };
+      mockWs.emit('message', Buffer.from(JSON.stringify(message)));
+
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        '📥 Remote webhook:received: test-plugin'
+      );
+      expect(onWebhookReceived).toHaveBeenCalledWith({
+        pluginName: 'test-plugin',
+        body: { action: 'update', id: '123' },
+        headers: { 'content-type': 'application/json' },
+        timestamp: '2024-01-01T00:00:00.000Z',
+      });
+    });
+
+    it('should not call callback when webhook:received but no callback configured', async () => {
+      const client = new UDLWebSocketClient({
+        url: 'ws://localhost:4000/ws',
+        // No onWebhookReceived callback
+      });
+      const store = createMockStore();
+
+      const connectPromise = client.connect(store);
+      mockWs.emit('open');
+      await connectPromise;
+
+      const message = {
+        type: 'webhook:received',
+        pluginName: 'test-plugin',
+        body: { action: 'update' },
+        headers: {},
+        timestamp: '2024-01-01T00:00:00.000Z',
+      };
+
+      // Should not throw when no callback is configured
+      expect(() => {
+        mockWs.emit('message', Buffer.from(JSON.stringify(message)));
+      }).not.toThrow();
+
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        '📥 Remote webhook:received: test-plugin'
+      );
+    });
+
+    it('should handle async callback errors in webhook:received gracefully', async () => {
+      // Use real timers for this test since we need proper async handling
+      vi.useRealTimers();
+
+      const onWebhookReceived = vi
+        .fn()
+        .mockRejectedValue(new Error('Callback failed'));
+      const client = new UDLWebSocketClient({
+        url: 'ws://localhost:4000/ws',
+        onWebhookReceived,
+      });
+
+      // Reset the mock WebSocket to use real handlers
+      const realMockWs = createMockWs();
+      (WebSocket as unknown as ReturnType<typeof vi.fn>).mockImplementation(
+        () => realMockWs
+      );
+
+      const store = createMockStore();
+      const connectPromise = client.connect(store);
+      realMockWs.emit('open');
+      await connectPromise;
+
+      const message = {
+        type: 'webhook:received',
+        pluginName: 'test-plugin',
+        body: {},
+        headers: {},
+        timestamp: '2024-01-01T00:00:00.000Z',
+      };
+      realMockWs.emit('message', Buffer.from(JSON.stringify(message)));
+
+      // Wait for the async error to be caught
+      await new Promise((resolve) => setTimeout(resolve, 10));
+
+      expect(consoleErrorSpy).toHaveBeenCalledWith(
+        '❌ Error processing relayed webhook:',
+        expect.any(Error)
+      );
+
+      // Restore fake timers for other tests
+      vi.useFakeTimers();
+    });
+
+    it('should skip node:created/updated when onWebhookReceived is configured', async () => {
+      const onWebhookReceived = vi.fn();
+      const client = new UDLWebSocketClient({
+        url: 'ws://localhost:4000/ws',
+        onWebhookReceived, // This enables local webhook handling
+      });
+      const store = createMockStore();
+
+      const connectPromise = client.connect(store);
+      mockWs.emit('open');
+      await connectPromise;
+
+      // Send node:created - should be skipped
+      const createMessage = {
+        type: 'node:created',
+        nodeId: 'prod-1',
+        nodeType: 'Product',
+        data: { id: 'prod-1', name: 'Test Product' },
+      };
+      mockWs.emit('message', Buffer.from(JSON.stringify(createMessage)));
+
+      // Send node:updated - should also be skipped
+      const updateMessage = {
+        type: 'node:updated',
+        nodeId: 'prod-1',
+        nodeType: 'Product',
+        data: { id: 'prod-1', name: 'Updated Product' },
+      };
+      mockWs.emit('message', Buffer.from(JSON.stringify(updateMessage)));
+
+      // store.set should NOT have been called since we handle webhooks locally
+      expect(store.set).not.toHaveBeenCalled();
+    });
+
+    it('should still handle node:deleted when onWebhookReceived is configured', async () => {
+      const onWebhookReceived = vi.fn();
+      const client = new UDLWebSocketClient({
+        url: 'ws://localhost:4000/ws',
+        onWebhookReceived, // This enables local webhook handling
+      });
+      const store = createMockStore();
+
+      const connectPromise = client.connect(store);
+      mockWs.emit('open');
+      await connectPromise;
+
+      // Send node:deleted - should still be handled
+      const deleteMessage = {
+        type: 'node:deleted',
+        nodeId: 'prod-1',
+        nodeType: 'Product',
+      };
+      mockWs.emit('message', Buffer.from(JSON.stringify(deleteMessage)));
+
+      // Deletions should still work even with local webhook handling
+      expect(store.delete).toHaveBeenCalledWith('prod-1');
+    });
+
     it('should not update store when data is missing on node:created', async () => {
       const client = new UDLWebSocketClient({ url: 'ws://localhost:4000/ws' });
       const store = createMockStore();
diff --git a/packages/core/tests/unit/websocket/server.test.ts b/packages/core/tests/unit/websocket/server.test.ts
index 49d8d73..b6e3de9 100644
--- a/packages/core/tests/unit/websocket/server.test.ts
+++ b/packages/core/tests/unit/websocket/server.test.ts
@@ -335,6 +335,70 @@ describe('UDLWebSocketServer', () => {
         client2.close();
       }
     });
+
+    it('broadcasts webhook:received to all clients', async () => {
+      client = new WebSocket(`ws://localhost:${serverPort}/ws`);
+      await waitForMessage(client); // connected message
+
+      const client2 = new WebSocket(`ws://localhost:${serverPort}/ws`);
+      await waitForMessage(client2); // connected message
+
+      try {
+        const webhook = {
+          pluginName: 'test-plugin',
+          body: { action: 'update', id: '123' },
+          headers: { 'content-type': 'application/json' },
+          timestamp: Date.now(),
+        };
+
+        wsServer.broadcastWebhookReceived(webhook);
+
+        const [message1, message2] = await Promise.all([
+          waitForMessage(client),
+          waitForMessage(client2),
+        ]);
+
+        expect(message1.type).toBe('webhook:received');
+        expect((message1 as { pluginName: string }).pluginName).toBe(
+          'test-plugin'
+        );
+        expect((message1 as { body: unknown }).body).toEqual({
+          action: 'update',
+          id: '123',
+        });
+
+        expect(message2.type).toBe('webhook:received');
+        expect((message2 as { pluginName: string }).pluginName).toBe(
+          'test-plugin'
+        );
+      } finally {
+        client2.close();
+      }
+    });
+
+    it('does not broadcast webhook:received to closed clients', async () => {
+      client = new WebSocket(`ws://localhost:${serverPort}/ws`);
+      await waitForMessage(client); // connected message
+
+      // Close the client
+      const closePromise = new Promise<void>((resolve) => {
+        client!.once('close', () => resolve());
+      });
+      client.close();
+      await closePromise;
+
+      // This should not throw even though client is closed
+      const webhook = {
+        pluginName: 'test-plugin',
+        body: {},
+        headers: {},
+        timestamp: Date.now(),
+      };
+      wsServer.broadcastWebhookReceived(webhook);
+
+      // If we get here without error, it correctly skipped the closed client
+      expect(client.readyState).toBe(WebSocket.CLOSED);
+    });
   });
 
   describe('close', () => {

From 617eccb56b69aa286c9034bf83e454e2651ef005 Mon Sep 17 00:00:00 2001
From: dawidurbanski <hi@dawidurbanski.com>
Date: Tue, 23 Dec 2025 12:31:26 +0100
Subject: [PATCH 41/46] chore: add test:package script and update package-lock

---
 package-lock.json | 3 +++
 package.json      | 1 +
 2 files changed, 4 insertions(+)

diff --git a/package-lock.json b/package-lock.json
index 408879c..16d60fa 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -11937,6 +11937,9 @@
       "bin": {
         "udl-next": "bin/udl-next.js"
       },
+      "devDependencies": {
+        "universal-data-layer": "*"
+      },
       "peerDependencies": {
         "next": ">=13.0.0",
         "universal-data-layer": "^1.0.6"
diff --git a/package.json b/package.json
index 66325a0..1ebef85 100644
--- a/package.json
+++ b/package.json
@@ -14,6 +14,7 @@
     "lint": "turbo lint --filter='./packages/*' --ui=stream",
     "fix": "turbo fix --filter='./packages/*' && npm run fix --prefix tests/manual",
     "test": "turbo test --filter='./packages/*' --ui=stream",
+    "test:package": "turbo test --ui=stream --filter",
     "test:coverage": "turbo test:coverage --filter='./packages/*' --ui=stream; exitcode=$?; node scripts/generate-coverage-index.js && node scripts/inject-coverage-nav.js; exit $exitcode",
     "test:coverage:file": "npm run test:coverage:file --workspace=universal-data-layer --",
     "codegen": "turbo codegen --filter='./packages/*' --ui=stream",

From 23937f172d7d25401eb157522fa8b72af05f10a8 Mon Sep 17 00:00:00 2001
From: dawidurbanski <hi@dawidurbanski.com>
Date: Tue, 23 Dec 2025 13:07:12 +0100
Subject: [PATCH 42/46] feat(core): add updateStrategy for sync-based source
 plugins

Add `updateStrategy` config option that allows plugins to specify how
incremental updates from webhooks should be handled:

- `'webhook'` (default): Process webhook payload directly via handler
- `'sync'`: Treat webhooks as notifications and re-run sourceNodes

This enables plugins with native sync APIs (like Contentful) to reuse
their existing sourceNodes logic for incremental updates, rather than
maintaining separate webhook transformation code.

Key changes:
- Add UpdateStrategy type and config option to UDLConfig
- Create PluginRegistry to store sourceNodes references
- Modify webhook processor to group by strategy and call sourceNodes
  once per sync-strategy plugin (not once per webhook)
- Update Contentful plugin to use updateStrategy: 'sync'
- Warn if both updateStrategy: 'sync' and registerWebhookHandler set
---
 .changeset/update-strategy-sync.md            | 32 +++++++
 packages/core/src/index.ts                    |  9 ++
 packages/core/src/loader.ts                   | 75 +++++++++++++++-
 packages/core/src/plugins/index.ts            | 10 +++
 packages/core/src/plugins/registry.ts         | 88 +++++++++++++++++++
 packages/core/src/webhooks/processor.ts       | 75 +++++++++++++++-
 .../plugin-source-contentful/udl.config.ts    |  6 ++
 7 files changed, 292 insertions(+), 3 deletions(-)
 create mode 100644 .changeset/update-strategy-sync.md
 create mode 100644 packages/core/src/plugins/index.ts
 create mode 100644 packages/core/src/plugins/registry.ts

diff --git a/.changeset/update-strategy-sync.md b/.changeset/update-strategy-sync.md
new file mode 100644
index 0000000..21db75a
--- /dev/null
+++ b/.changeset/update-strategy-sync.md
@@ -0,0 +1,32 @@
+---
+'universal-data-layer': minor
+'@universal-data-layer/plugin-source-contentful': patch
+---
+
+# Add `updateStrategy` config option for sync-based source plugins
+
+Plugins can now specify how incremental updates from webhooks should be handled:
+
+- `'webhook'` (default): Process webhook payload directly via `registerWebhookHandler` or the default CRUD handler
+- `'sync'`: Treat webhooks as notifications only and re-run `sourceNodes` to fetch changes via the plugin's sync API
+
+This enables plugins with native sync APIs (like Contentful) to reuse their existing `sourceNodes` logic for incremental updates, eliminating the need to maintain separate webhook transformation code.
+
+## Usage
+
+```typescript
+// For sources with sync APIs (like Contentful)
+export const config = defineConfig({
+  name: 'my-source-plugin',
+  updateStrategy: 'sync',
+});
+```
+
+When webhooks arrive for a plugin with `updateStrategy: 'sync'`:
+
+1. Webhooks are batched as usual (debounced)
+2. After the batch, `sourceNodes` is called once per affected plugin
+3. The plugin's delta sync fetches only changed data
+4. Cache is saved after sync completes
+
+The Contentful plugin now uses `updateStrategy: 'sync'` by default, leveraging the Contentful Sync API for efficient incremental updates.
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index fd7b05e..22c1ff2 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -23,6 +23,7 @@ export {
   type LoadPluginsOptions,
   type RegisterTypesContext,
   type CodegenConfig,
+  type UpdateStrategy,
 } from './loader.js';
 
 // Re-export codegen integration
@@ -188,3 +189,11 @@ export type { WebSocketConfig } from './loader.js';
 
 // Export the default server for programmatic usage
 export { default } from './server.js';
+
+// Re-export plugin registry
+export {
+  PluginRegistry,
+  defaultPluginRegistry,
+  type RegisteredPlugin,
+  type SourceNodesFn,
+} from './plugins/index.js';
diff --git a/packages/core/src/loader.ts b/packages/core/src/loader.ts
index eee1645..4ee8ea7 100644
--- a/packages/core/src/loader.ts
+++ b/packages/core/src/loader.ts
@@ -26,6 +26,7 @@ import {
   type WebhookHooksConfig,
   type PluginWebhookHandler,
 } from '@/webhooks/index.js';
+import { defaultPluginRegistry, type PluginRegistry } from '@/plugins/index.js';
 import type { ServerOptions as WebSocketServerOptions } from 'ws';
 
 export const pluginTypes = ['core', 'source', 'other'] as const;
@@ -250,6 +251,18 @@ export interface RemoteConfig {
   websockets?: WebSocketConfig;
 }
 
+/**
+ * Strategy for handling incremental updates from webhooks.
+ *
+ * - `'webhook'` (default): Process webhook payload directly via `registerWebhookHandler`
+ *   or the default CRUD handler. Use this when the webhook payload contains the data.
+ *
+ * - `'sync'`: Webhooks are treated as notifications only. When received, the plugin's
+ *   `sourceNodes` function is re-invoked to fetch changes via its sync API.
+ *   Use this when the source has its own sync/delta API (e.g., Contentful Sync API).
+ */
+export type UpdateStrategy = 'webhook' | 'sync';
+
 /**
  * Core UDL configuration object
  */
@@ -285,6 +298,19 @@ export interface UDLConfig {
 
   /** Additional indexed fields for this plugin (for source plugins) */
   indexes?: string[];
+  /**
+   * Strategy for handling incremental updates from webhooks.
+   *
+   * - `'webhook'` (default): Process webhook payload directly via `registerWebhookHandler`
+   *   or the default CRUD handler. Use this when the webhook payload contains the data.
+   *
+   * - `'sync'`: Webhooks are treated as notifications only. When received, the plugin's
+   *   `sourceNodes` function is re-invoked to fetch changes via its sync API.
+   *   Use this when the source has its own sync/delta API (e.g., Contentful Sync API).
+   *
+   * @default 'webhook'
+   */
+  updateStrategy?: UpdateStrategy;
   /** Code generation configuration - when set, automatically generates types after sourceNodes */
   codegen?: CodegenConfig;
   /**
@@ -584,6 +610,11 @@ export interface LoadPluginsOptions {
    * If not provided, uses the defaultWebhookRegistry singleton.
    */
   webhookRegistry?: WebhookRegistry;
+  /**
+   * Plugin registry for storing plugin information.
+   * If not provided, uses the defaultPluginRegistry singleton.
+   */
+  pluginRegistry?: PluginRegistry;
   /**
    * Indicates this is a local development instance syncing from a remote UDL.
    * When true, plugins are loaded and webhook handlers are registered,
@@ -721,6 +752,7 @@ export async function loadPlugins(
     cache: cacheEnabled = true,
     cacheDir,
     webhookRegistry = defaultWebhookRegistry,
+    pluginRegistry = defaultPluginRegistry,
   } = options ?? {};
   const nodeStore = store ?? defaultStore;
   const codegenConfigs: PluginCodegenInfo[] = [];
@@ -872,15 +904,53 @@ export async function loadPlugins(
           }
         }
 
+        // Get update strategy (default: 'webhook')
+        const updateStrategy = module.config?.updateStrategy ?? 'webhook';
+
+        // Warn if both updateStrategy: 'sync' and registerWebhookHandler are provided
+        if (updateStrategy === 'sync' && module.registerWebhookHandler) {
+          console.warn(
+            `⚠️ [${actualPluginName}] registerWebhookHandler is ignored when updateStrategy is "sync". ` +
+              `Use onWebhookReceived hook for webhook filtering/validation.`
+          );
+        }
+
+        // Register plugin in the registry for webhook processor to use
+        pluginRegistry.register({
+          name: actualPluginName,
+          sourceNodes: module.sourceNodes,
+          updateStrategy,
+          sourceNodesContext: module.sourceNodes
+            ? {
+                createNodeId,
+                createContentDigest,
+                options: context?.options,
+                cacheDir: cacheLocation,
+              }
+            : undefined,
+          store: nodeStore,
+        });
+
         // Register webhook handler for the plugin (always, regardless of isLocal)
-        // If plugin exports registerWebhookHandler, use it instead of default
-        if (module.registerWebhookHandler) {
+        // For 'sync' strategy, we register a no-op handler - the processor will
+        // re-invoke sourceNodes instead of processing the webhook payload
+        if (updateStrategy === 'sync') {
+          // Register a placeholder handler for sync strategy plugins
+          // The actual work is done by the webhook processor calling sourceNodes
+          registerDefaultWebhook(
+            webhookRegistry,
+            actualPluginName,
+            pluginIdField
+          );
+        } else if (module.registerWebhookHandler) {
+          // Use plugin's custom handler for 'webhook' strategy
           registerPluginWebhookHandler(
             webhookRegistry,
             actualPluginName,
             module.registerWebhookHandler
           );
         } else {
+          // Use default CRUD handler for 'webhook' strategy
           registerDefaultWebhook(
             webhookRegistry,
             actualPluginName,
@@ -922,6 +992,7 @@ export async function loadPlugins(
             // Nested plugins store their cache in the parent plugin's directory
             cacheDir: pluginPath,
             webhookRegistry,
+            pluginRegistry,
           });
 
           codegenConfigs.push(...nestedResult.codegenConfigs);
diff --git a/packages/core/src/plugins/index.ts b/packages/core/src/plugins/index.ts
new file mode 100644
index 0000000..3bde397
--- /dev/null
+++ b/packages/core/src/plugins/index.ts
@@ -0,0 +1,10 @@
+/**
+ * Plugin system exports
+ */
+
+export {
+  PluginRegistry,
+  defaultPluginRegistry,
+  type RegisteredPlugin,
+  type SourceNodesFn,
+} from './registry.js';
diff --git a/packages/core/src/plugins/registry.ts b/packages/core/src/plugins/registry.ts
new file mode 100644
index 0000000..5c462af
--- /dev/null
+++ b/packages/core/src/plugins/registry.ts
@@ -0,0 +1,88 @@
+/**
+ * Plugin Registry
+ *
+ * Stores plugin information including sourceNodes functions and their context.
+ * Used by the webhook processor to re-invoke sourceNodes for plugins with
+ * updateStrategy: 'sync'.
+ */
+
+import type { NodeStore } from '@/nodes/store.js';
+import type { SourceNodesContext } from '@/nodes/index.js';
+import type { UpdateStrategy } from '@/loader.js';
+
+/**
+ * Function signature for a plugin's sourceNodes export.
+ * Uses a generic to match the UDLConfigFile.sourceNodes signature.
+ */
+export type SourceNodesFn = <T = Record<string, unknown>>(
+  context?: SourceNodesContext<T>
+) => void | Promise<void>;
+
+/**
+ * Information about a registered plugin needed for re-invoking sourceNodes.
+ */
+export interface RegisteredPlugin {
+  /** The plugin name */
+  name: string;
+  /** The plugin's sourceNodes function (if it has one) */
+  sourceNodes: SourceNodesFn | undefined;
+  /** The update strategy for handling webhooks */
+  updateStrategy: UpdateStrategy;
+  /** The context to pass when re-invoking sourceNodes */
+  sourceNodesContext: Omit<SourceNodesContext<unknown>, 'actions'> | undefined;
+  /** The node store to use for creating actions */
+  store: NodeStore | undefined;
+}
+
+/**
+ * Registry for storing plugin information.
+ * Singleton pattern - use defaultPluginRegistry for most cases.
+ */
+export class PluginRegistry {
+  private plugins = new Map<string, RegisteredPlugin>();
+
+  /**
+   * Register a plugin with its sourceNodes function and context.
+   */
+  register(plugin: RegisteredPlugin): void {
+    this.plugins.set(plugin.name, plugin);
+  }
+
+  /**
+   * Get a registered plugin by name.
+   */
+  get(pluginName: string): RegisteredPlugin | undefined {
+    return this.plugins.get(pluginName);
+  }
+
+  /**
+   * Check if a plugin is registered.
+   */
+  has(pluginName: string): boolean {
+    return this.plugins.has(pluginName);
+  }
+
+  /**
+   * Get all registered plugins.
+   */
+  getAll(): RegisteredPlugin[] {
+    return Array.from(this.plugins.values());
+  }
+
+  /**
+   * Get all plugins with a specific update strategy.
+   */
+  getByStrategy(strategy: UpdateStrategy): RegisteredPlugin[] {
+    return this.getAll().filter((p) => p.updateStrategy === strategy);
+  }
+
+  /**
+   * Clear all registered plugins (primarily for testing).
+   */
+  clear(): void {
+    this.plugins.clear();
+  }
+}
+
+/** Default singleton plugin registry */
+export const defaultPluginRegistry = new PluginRegistry();
diff --git a/packages/core/src/webhooks/processor.ts b/packages/core/src/webhooks/processor.ts
index d25ae9e..6c0839d 100644
--- a/packages/core/src/webhooks/processor.ts
+++ b/packages/core/src/webhooks/processor.ts
@@ -18,6 +18,8 @@ import { defaultStore } from '@/nodes/defaultStore.js';
 import { createNodeActions } from '@/nodes/actions/index.js';
 import type { WebhookHandlerContext } from './types.js';
 import { DEFAULT_WEBHOOK_PATH } from './default-handler.js';
+import { defaultPluginRegistry } from '@/plugins/index.js';
+import { savePluginCache } from '@/cache/manager.js';
 
 /**
  * Create a minimal mock IncomingMessage for queued webhook processing.
@@ -174,10 +176,59 @@ export function initializeWebhookProcessor(): void {
   console.log('🔗 Webhook processor initialized');
 }
 
+/**
+ * Re-invoke a plugin's sourceNodes function.
+ * Used for plugins with updateStrategy: 'sync'.
+ */
+async function invokeSourceNodes(pluginName: string): Promise<void> {
+  const plugin = defaultPluginRegistry.get(pluginName);
+
+  if (!plugin) {
+    console.warn(`⚠️ Plugin not found in registry: ${pluginName}`);
+    return;
+  }
+
+  if (!plugin.sourceNodes || !plugin.sourceNodesContext || !plugin.store) {
+    console.warn(
+      `⚠️ Plugin ${pluginName} has updateStrategy: 'sync' but no sourceNodes function`
+    );
+    return;
+  }
+
+  console.log(`🔄 [${pluginName}] Re-syncing via sourceNodes...`);
+
+  try {
+    // Create fresh actions for this plugin
+    const actions = createNodeActions({
+      store: plugin.store,
+      owner: pluginName,
+    });
+
+    // Invoke sourceNodes with the stored context
+    await plugin.sourceNodes({
+      ...plugin.sourceNodesContext,
+      actions,
+    });
+
+    // Save updated cache
+    await savePluginCache(pluginName);
+
+    console.log(`✅ [${pluginName}] Re-sync complete`);
+  } catch (error) {
+    console.error(`❌ [${pluginName}] Re-sync failed:`, error);
+  }
+}
+
 /**
  * Process a batch of webhooks with lifecycle hooks.
  * This is called by the queue before emitting individual webhook:process events.
  *
+ * For plugins with updateStrategy: 'sync', the batch is processed by
+ * re-invoking sourceNodes once per affected plugin (not once per webhook).
+ *
+ * For plugins with updateStrategy: 'webhook', each webhook is processed
+ * individually via the registered handler.
+ *
  * @param webhooks - The webhooks to process
  * @returns The processed batch
  */
@@ -208,11 +259,33 @@ export async function processWebhookBatch(
     }
   }
 
-  // Process each webhook
+  // Group webhooks by plugin and strategy
+  const syncPlugins = new Set<string>();
+  const webhookStrategyWebhooks: QueuedWebhook[] = [];
+
   for (const webhook of webhooks) {
+    const plugin = defaultPluginRegistry.get(webhook.pluginName);
+    const strategy = plugin?.updateStrategy ?? 'webhook';
+
+    if (strategy === 'sync') {
+      // Collect unique plugin names for sync strategy
+      syncPlugins.add(webhook.pluginName);
+    } else {
+      // Queue for individual processing
+      webhookStrategyWebhooks.push(webhook);
+    }
+  }
+
+  // Process webhooks with 'webhook' strategy individually
+  for (const webhook of webhookStrategyWebhooks) {
     await processWebhook(webhook);
   }
 
+  // Process plugins with 'sync' strategy - call sourceNodes once per plugin
+  for (const pluginName of syncPlugins) {
+    await invokeSourceNodes(pluginName);
+  }
+
   batch.completedAt = Date.now();
   return batch;
 }
diff --git a/packages/plugin-source-contentful/udl.config.ts b/packages/plugin-source-contentful/udl.config.ts
index 8ed6b14..44afc24 100644
--- a/packages/plugin-source-contentful/udl.config.ts
+++ b/packages/plugin-source-contentful/udl.config.ts
@@ -53,6 +53,12 @@ export const config = defineConfig({
   type: 'source',
   name: '@universal-data-layer/plugin-source-contentful',
   indexes: ['contentfulId'],
+  /**
+   * Use 'sync' strategy because Contentful has its own Sync API.
+   * When webhooks arrive, sourceNodes will be re-invoked to fetch
+   * changes via the Sync API (delta sync using stored token).
+   */
+  updateStrategy: 'sync',
   codegen: {
     output: './generated',
     guards: true,

From 5c41b99aa7b7cd016ebfa8c2d85b3ead59c9fc07 Mon Sep 17 00:00:00 2001
From: dawidurbanski <hi@dawidurbanski.com>
Date: Tue, 23 Dec 2025 13:17:01 +0100
Subject: [PATCH 43/46] test(core): add tests for updateStrategy and plugin
 registry

Add comprehensive tests for the new updateStrategy feature:

- Add registry.test.ts with 100% coverage for PluginRegistry class
- Add tests for updateStrategy: 'sync' in loader.test.ts
  - Verifies sync plugins register default webhook handler
  - Verifies warning when both sync strategy and custom handler provided
- Add tests for sync strategy in processor.test.ts
  - Tests invokeSourceNodes function (success, errors, missing plugin)
  - Tests deduplication (multiple webhooks -> one sync)
  - Tests mixed strategies (sync + webhook plugins in same batch)

All target files now have 100% test coverage.
---
 .../core/tests/integration/loader.test.ts     | 117 ++++++++
 .../core/tests/unit/plugins/registry.test.ts  | 247 ++++++++++++++++
 .../tests/unit/webhooks/processor.test.ts     | 271 ++++++++++++++++++
 3 files changed, 635 insertions(+)
 create mode 100644 packages/core/tests/unit/plugins/registry.test.ts

diff --git a/packages/core/tests/integration/loader.test.ts b/packages/core/tests/integration/loader.test.ts
index dde6179..6c58934 100644
--- a/packages/core/tests/integration/loader.test.ts
+++ b/packages/core/tests/integration/loader.test.ts
@@ -1969,5 +1969,122 @@ describe('loader integration tests', () => {
 
       consoleLogSpy.mockRestore();
     });
+
+    it('should register default webhook handler for updateStrategy sync plugins', async () => {
+      const { WebhookRegistry } = await import('@/webhooks/registry.js');
+
+      const pluginDir = join(pluginsDir, 'sync-strategy-plugin');
+      mkdirSync(pluginDir, { recursive: true });
+
+      writeFileSync(
+        join(pluginDir, 'udl.config.js'),
+        `
+        export const config = {
+          name: 'sync-strategy-plugin',
+          updateStrategy: 'sync'
+        };
+
+        export async function sourceNodes({ actions, createNodeId }) {
+          await actions.createNode({
+            internal: {
+              id: createNodeId('SyncNode', '1'),
+              type: 'SyncNode',
+            },
+            parent: undefined,
+            children: undefined,
+          });
+        }
+        // No registerWebhookHandler - for sync strategy, default handler is used
+        `
+      );
+
+      const { NodeStore } = await import('@/nodes/index.js');
+      const consoleLogSpy = vi
+        .spyOn(console, 'log')
+        .mockImplementation(() => {});
+
+      const store = new NodeStore();
+      const webhookRegistry = new WebhookRegistry();
+
+      await loadPlugins([pluginDir], {
+        appConfig: {},
+        store,
+        cache: false,
+        webhookRegistry,
+      });
+
+      // Verify the default handler was registered for sync strategy
+      expect(webhookRegistry.has('sync-strategy-plugin')).toBe(true);
+
+      const handler = webhookRegistry.getHandler('sync-strategy-plugin');
+      expect(handler).toBeDefined();
+
+      consoleLogSpy.mockRestore();
+    });
+
+    it('should warn when updateStrategy is sync and registerWebhookHandler is also provided', async () => {
+      const { WebhookRegistry } = await import('@/webhooks/registry.js');
+
+      const pluginDir = join(pluginsDir, 'sync-with-handler-plugin');
+      mkdirSync(pluginDir, { recursive: true });
+
+      writeFileSync(
+        join(pluginDir, 'udl.config.js'),
+        `
+        export const config = {
+          name: 'sync-with-handler-plugin',
+          updateStrategy: 'sync'
+        };
+
+        export async function sourceNodes({ actions, createNodeId }) {
+          await actions.createNode({
+            internal: {
+              id: createNodeId('SyncHandlerNode', '1'),
+              type: 'SyncHandlerNode',
+            },
+            parent: undefined,
+            children: undefined,
+          });
+        }
+
+        // This handler should be ignored when updateStrategy is 'sync'
+        export async function registerWebhookHandler({ res }) {
+          res.writeHead(200);
+          res.end('Custom handler');
+        }
+        `
+      );
+
+      const { NodeStore } = await import('@/nodes/index.js');
+      const consoleLogSpy = vi
+        .spyOn(console, 'log')
+        .mockImplementation(() => {});
+      const consoleWarnSpy = vi
+        .spyOn(console, 'warn')
+        .mockImplementation(() => {});
+
+      const store = new NodeStore();
+      const webhookRegistry = new WebhookRegistry();
+
+      await loadPlugins([pluginDir], {
+        appConfig: {},
+        store,
+        cache: false,
+        webhookRegistry,
+      });
+
+      // Should warn that registerWebhookHandler is ignored
+      expect(consoleWarnSpy).toHaveBeenCalledWith(
+        expect.stringContaining(
+          'registerWebhookHandler is ignored when updateStrategy is "sync"'
+        )
+      );
+
+      // The default handler should still be registered (not the custom one)
+      expect(webhookRegistry.has('sync-with-handler-plugin')).toBe(true);
+
+      consoleLogSpy.mockRestore();
+      consoleWarnSpy.mockRestore();
+    });
   });
 });
diff --git a/packages/core/tests/unit/plugins/registry.test.ts b/packages/core/tests/unit/plugins/registry.test.ts
new file mode 100644
index 0000000..7dd1cfb
--- /dev/null
+++ b/packages/core/tests/unit/plugins/registry.test.ts
@@ -0,0 +1,247 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import {
+  PluginRegistry,
+  defaultPluginRegistry,
+  type RegisteredPlugin,
+} from '@/plugins/registry.js';
+
+describe('PluginRegistry', () => {
+  let registry: PluginRegistry;
+
+  beforeEach(() => {
+    registry = new PluginRegistry();
+  });
+
+  describe('register', () => {
+    it('should register a plugin', () => {
+      const plugin: RegisteredPlugin = {
+        name: 'test-plugin',
+        sourceNodes: undefined,
+        updateStrategy: 'webhook',
+        sourceNodesContext: undefined,
+        store: undefined,
+      };
+
+      registry.register(plugin);
+
+      expect(registry.get('test-plugin')).toBe(plugin);
+    });
+
+    it('should overwrite existing plugin with same name', () => {
+      const plugin1: RegisteredPlugin = {
+        name: 'test-plugin',
+        sourceNodes: undefined,
+        updateStrategy: 'webhook',
+        sourceNodesContext: undefined,
+        store: undefined,
+      };
+
+      const plugin2: RegisteredPlugin = {
+        name: 'test-plugin',
+        sourceNodes: undefined,
+        updateStrategy: 'sync',
+        sourceNodesContext: undefined,
+        store: undefined,
+      };
+
+      registry.register(plugin1);
+      registry.register(plugin2);
+
+      expect(registry.get('test-plugin')).toBe(plugin2);
+      expect(registry.get('test-plugin')?.updateStrategy).toBe('sync');
+    });
+  });
+
+  describe('get', () => {
+    it('should return undefined for non-existent plugin', () => {
+      expect(registry.get('non-existent')).toBeUndefined();
+    });
+
+    it('should return the registered plugin', () => {
+      const plugin: RegisteredPlugin = {
+        name: 'my-plugin',
+        sourceNodes: undefined,
+        updateStrategy: 'sync',
+        sourceNodesContext: undefined,
+        store: undefined,
+      };
+
+      registry.register(plugin);
+
+      expect(registry.get('my-plugin')).toBe(plugin);
+    });
+  });
+
+  describe('has', () => {
+    it('should return false for non-existent plugin', () => {
+      expect(registry.has('non-existent')).toBe(false);
+    });
+
+    it('should return true for registered plugin', () => {
+      const plugin: RegisteredPlugin = {
+        name: 'existing-plugin',
+        sourceNodes: undefined,
+        updateStrategy: 'webhook',
+        sourceNodesContext: undefined,
+        store: undefined,
+      };
+
+      registry.register(plugin);
+
+      expect(registry.has('existing-plugin')).toBe(true);
+    });
+  });
+
+  describe('getAll', () => {
+    it('should return empty array when no plugins registered', () => {
+      expect(registry.getAll()).toEqual([]);
+    });
+
+    it('should return all registered plugins', () => {
+      const plugin1: RegisteredPlugin = {
+        name: 'plugin-1',
+        sourceNodes: undefined,
+        updateStrategy: 'webhook',
+        sourceNodesContext: undefined,
+        store: undefined,
+      };
+
+      const plugin2: RegisteredPlugin = {
+        name: 'plugin-2',
+        sourceNodes: undefined,
+        updateStrategy: 'sync',
+        sourceNodesContext: undefined,
+        store: undefined,
+      };
+
+      registry.register(plugin1);
+      registry.register(plugin2);
+
+      const all = registry.getAll();
+      expect(all).toHaveLength(2);
+      expect(all).toContain(plugin1);
+      expect(all).toContain(plugin2);
+    });
+  });
+
+  describe('getByStrategy', () => {
+    it('should return empty array when no plugins match strategy', () => {
+      const plugin: RegisteredPlugin = {
+        name: 'webhook-plugin',
+        sourceNodes: undefined,
+        updateStrategy: 'webhook',
+        sourceNodesContext: undefined,
+        store: undefined,
+      };
+
+      registry.register(plugin);
+
+      expect(registry.getByStrategy('sync')).toEqual([]);
+    });
+
+    it('should return plugins with matching strategy', () => {
+      const webhookPlugin: RegisteredPlugin = {
+        name: 'webhook-plugin',
+        sourceNodes: undefined,
+        updateStrategy: 'webhook',
+        sourceNodesContext: undefined,
+        store: undefined,
+      };
+
+      const syncPlugin1: RegisteredPlugin = {
+        name: 'sync-plugin-1',
+        sourceNodes: undefined,
+        updateStrategy: 'sync',
+        sourceNodesContext: undefined,
+        store: undefined,
+      };
+
+      const syncPlugin2: RegisteredPlugin = {
+        name: 'sync-plugin-2',
+        sourceNodes: undefined,
+        updateStrategy: 'sync',
+        sourceNodesContext: undefined,
+        store: undefined,
+      };
+
+      registry.register(webhookPlugin);
+      registry.register(syncPlugin1);
+      registry.register(syncPlugin2);
+
+      const syncPlugins = registry.getByStrategy('sync');
+      expect(syncPlugins).toHaveLength(2);
+      expect(syncPlugins).toContain(syncPlugin1);
+      expect(syncPlugins).toContain(syncPlugin2);
+      expect(syncPlugins).not.toContain(webhookPlugin);
+
+      const webhookPlugins = registry.getByStrategy('webhook');
+      expect(webhookPlugins).toHaveLength(1);
+      expect(webhookPlugins).toContain(webhookPlugin);
+    });
+
+    it('should return empty array when registry is empty', () => {
+      expect(registry.getByStrategy('webhook')).toEqual([]);
+      expect(registry.getByStrategy('sync')).toEqual([]);
+    });
+  });
+
+  describe('clear', () => {
+    it('should remove all registered plugins', () => {
+      const plugin1: RegisteredPlugin = {
+        name: 'plugin-1',
+        sourceNodes: undefined,
+        updateStrategy: 'webhook',
+        sourceNodesContext: undefined,
+        store: undefined,
+      };
+
+      const plugin2: RegisteredPlugin = {
+        name: 'plugin-2',
+        sourceNodes: undefined,
+        updateStrategy: 'sync',
+        sourceNodesContext: undefined,
+        store: undefined,
+      };
+
+      registry.register(plugin1);
+      registry.register(plugin2);
+
+      expect(registry.getAll()).toHaveLength(2);
+
+      registry.clear();
+
+      expect(registry.getAll()).toEqual([]);
+      expect(registry.has('plugin-1')).toBe(false);
+      expect(registry.has('plugin-2')).toBe(false);
+    });
+
+    it('should work on empty registry', () => {
+      registry.clear();
+      expect(registry.getAll()).toEqual([]);
+    });
+  });
+});
+
+describe('defaultPluginRegistry', () => {
+  beforeEach(() => {
+    defaultPluginRegistry.clear();
+  });
+
+  it('should be an instance of PluginRegistry', () => {
+    expect(defaultPluginRegistry).toBeInstanceOf(PluginRegistry);
+  });
+
+  it('should be a singleton', () => {
+    const plugin: RegisteredPlugin = {
+      name: 'singleton-test',
+      sourceNodes: undefined,
+      updateStrategy: 'webhook',
+      sourceNodesContext: undefined,
+      store: undefined,
+    };
+
+    defaultPluginRegistry.register(plugin);
+
+    expect(defaultPluginRegistry.get('singleton-test')).toBe(plugin);
+  });
+});
diff --git a/packages/core/tests/unit/webhooks/processor.test.ts b/packages/core/tests/unit/webhooks/processor.test.ts
index a236414..051f303 100644
--- a/packages/core/tests/unit/webhooks/processor.test.ts
+++ b/packages/core/tests/unit/webhooks/processor.test.ts
@@ -38,6 +38,16 @@ vi.mock('@/nodes/actions/index.js', () => ({
   })),
 }));
 
+vi.mock('@/plugins/index.js', () => ({
+  defaultPluginRegistry: {
+    get: vi.fn(),
+  },
+}));
+
+vi.mock('@/cache/manager.js', () => ({
+  savePluginCache: vi.fn().mockResolvedValue(undefined),
+}));
+
 import {
   initializeWebhookProcessor,
   processWebhookBatch,
@@ -46,6 +56,8 @@ import { defaultWebhookRegistry } from '@/webhooks/registry.js';
 import { defaultWebhookQueue } from '@/webhooks/queue.js';
 import { getWebhookHooks } from '@/webhooks/hooks.js';
 import { createNodeActions } from '@/nodes/actions/index.js';
+import { defaultPluginRegistry } from '@/plugins/index.js';
+import { savePluginCache } from '@/cache/manager.js';
 import type { QueuedWebhook } from '@/webhooks/queue.js';
 
 describe('webhooks/processor', () => {
@@ -573,4 +585,263 @@ describe('webhooks/processor', () => {
       expect(mockHandler).toHaveBeenCalled();
     });
   });
+
+  describe('updateStrategy: sync', () => {
+    it('should call sourceNodes for plugins with sync strategy', async () => {
+      const mockSourceNodes = vi.fn().mockResolvedValue(undefined);
+      const mockStore = { get: vi.fn(), set: vi.fn() };
+
+      vi.mocked(defaultPluginRegistry.get).mockReturnValue({
+        name: 'sync-plugin',
+        sourceNodes: mockSourceNodes,
+        updateStrategy: 'sync',
+        sourceNodesContext: {
+          createNodeId: vi.fn(),
+          createContentDigest: vi.fn(),
+          options: {},
+          cacheDir: '/test',
+        },
+        store: mockStore as never,
+      });
+      vi.mocked(getWebhookHooks).mockReturnValue({});
+
+      const webhook = createQueuedWebhook({ pluginName: 'sync-plugin' });
+
+      await processWebhookBatch([webhook]);
+
+      expect(mockSourceNodes).toHaveBeenCalled();
+      expect(savePluginCache).toHaveBeenCalledWith('sync-plugin');
+      expect(mockConsoleLog).toHaveBeenCalledWith(
+        '🔄 [sync-plugin] Re-syncing via sourceNodes...'
+      );
+      expect(mockConsoleLog).toHaveBeenCalledWith(
+        '✅ [sync-plugin] Re-sync complete'
+      );
+    });
+
+    it('should warn when plugin is not found in registry for sync strategy', async () => {
+      vi.mocked(defaultPluginRegistry.get).mockReturnValue(undefined);
+      vi.mocked(getWebhookHooks).mockReturnValue({});
+      // Ensure the webhook handler is not found either to avoid fallback
+      vi.mocked(defaultWebhookRegistry.getHandler).mockReturnValue(undefined);
+
+      // Force the code path by creating a scenario where plugin is found
+      // but then removed from registry before invokeSourceNodes
+      const mockPluginOnFirstCall = {
+        name: 'disappearing-plugin',
+        sourceNodes: vi.fn(),
+        updateStrategy: 'sync' as const,
+        sourceNodesContext: undefined,
+        store: undefined,
+      };
+
+      // First call returns plugin (for strategy check), second returns undefined
+      vi.mocked(defaultPluginRegistry.get)
+        .mockReturnValueOnce(mockPluginOnFirstCall)
+        .mockReturnValueOnce(undefined);
+
+      const webhook = createQueuedWebhook({
+        pluginName: 'disappearing-plugin',
+      });
+
+      await processWebhookBatch([webhook]);
+
+      expect(mockConsoleWarn).toHaveBeenCalledWith(
+        '⚠️ Plugin not found in registry: disappearing-plugin'
+      );
+    });
+
+    it('should warn when sync plugin has no sourceNodes function', async () => {
+      vi.mocked(defaultPluginRegistry.get).mockReturnValue({
+        name: 'no-sourceNodes-plugin',
+        sourceNodes: undefined,
+        updateStrategy: 'sync',
+        sourceNodesContext: undefined,
+        store: undefined,
+      });
+      vi.mocked(getWebhookHooks).mockReturnValue({});
+
+      const webhook = createQueuedWebhook({
+        pluginName: 'no-sourceNodes-plugin',
+      });
+
+      await processWebhookBatch([webhook]);
+
+      expect(mockConsoleWarn).toHaveBeenCalledWith(
+        "⚠️ Plugin no-sourceNodes-plugin has updateStrategy: 'sync' but no sourceNodes function"
+      );
+    });
+
+    it('should warn when sync plugin has no sourceNodesContext', async () => {
+      vi.mocked(defaultPluginRegistry.get).mockReturnValue({
+        name: 'no-context-plugin',
+        sourceNodes: vi.fn(),
+        updateStrategy: 'sync',
+        sourceNodesContext: undefined,
+        store: { get: vi.fn() } as never,
+      });
+      vi.mocked(getWebhookHooks).mockReturnValue({});
+
+      const webhook = createQueuedWebhook({ pluginName: 'no-context-plugin' });
+
+      await processWebhookBatch([webhook]);
+
+      expect(mockConsoleWarn).toHaveBeenCalledWith(
+        "⚠️ Plugin no-context-plugin has updateStrategy: 'sync' but no sourceNodes function"
+      );
+    });
+
+    it('should warn when sync plugin has no store', async () => {
+      vi.mocked(defaultPluginRegistry.get).mockReturnValue({
+        name: 'no-store-plugin',
+        sourceNodes: vi.fn(),
+        updateStrategy: 'sync',
+        sourceNodesContext: {
+          createNodeId: vi.fn(),
+          createContentDigest: vi.fn(),
+          options: {},
+          cacheDir: '/test',
+        },
+        store: undefined,
+      });
+      vi.mocked(getWebhookHooks).mockReturnValue({});
+
+      const webhook = createQueuedWebhook({ pluginName: 'no-store-plugin' });
+
+      await processWebhookBatch([webhook]);
+
+      expect(mockConsoleWarn).toHaveBeenCalledWith(
+        "⚠️ Plugin no-store-plugin has updateStrategy: 'sync' but no sourceNodes function"
+      );
+    });
+
+    it('should catch and log sourceNodes errors without rethrowing', async () => {
+      const sourceNodesError = new Error('sourceNodes failed');
+      const mockSourceNodes = vi.fn().mockRejectedValue(sourceNodesError);
+      const mockStore = { get: vi.fn(), set: vi.fn() };
+
+      vi.mocked(defaultPluginRegistry.get).mockReturnValue({
+        name: 'error-plugin',
+        sourceNodes: mockSourceNodes,
+        updateStrategy: 'sync',
+        sourceNodesContext: {
+          createNodeId: vi.fn(),
+          createContentDigest: vi.fn(),
+          options: {},
+          cacheDir: '/test',
+        },
+        store: mockStore as never,
+      });
+      vi.mocked(getWebhookHooks).mockReturnValue({});
+
+      const webhook = createQueuedWebhook({ pluginName: 'error-plugin' });
+
+      // Should not throw
+      await processWebhookBatch([webhook]);
+
+      expect(mockConsoleError).toHaveBeenCalledWith(
+        '❌ [error-plugin] Re-sync failed:',
+        sourceNodesError
+      );
+    });
+
+    it('should only call sourceNodes once per plugin even with multiple webhooks', async () => {
+      const mockSourceNodes = vi.fn().mockResolvedValue(undefined);
+      const mockStore = { get: vi.fn(), set: vi.fn() };
+
+      vi.mocked(defaultPluginRegistry.get).mockReturnValue({
+        name: 'sync-plugin',
+        sourceNodes: mockSourceNodes,
+        updateStrategy: 'sync',
+        sourceNodesContext: {
+          createNodeId: vi.fn(),
+          createContentDigest: vi.fn(),
+          options: {},
+          cacheDir: '/test',
+        },
+        store: mockStore as never,
+      });
+      vi.mocked(getWebhookHooks).mockReturnValue({});
+
+      const webhooks = [
+        createQueuedWebhook({ pluginName: 'sync-plugin' }),
+        createQueuedWebhook({ pluginName: 'sync-plugin' }),
+        createQueuedWebhook({ pluginName: 'sync-plugin' }),
+      ];
+
+      await processWebhookBatch(webhooks);
+
+      // Should only be called once despite 3 webhooks
+      expect(mockSourceNodes).toHaveBeenCalledTimes(1);
+    });
+
+    it('should process webhook strategy webhooks normally alongside sync strategy', async () => {
+      const mockSourceNodes = vi.fn().mockResolvedValue(undefined);
+      const mockStore = { get: vi.fn(), set: vi.fn() };
+      const mockHandler = vi.fn().mockResolvedValue(undefined);
+
+      // sync-plugin uses sync strategy
+      vi.mocked(defaultPluginRegistry.get).mockImplementation((name) => {
+        if (name === 'sync-plugin') {
+          return {
+            name: 'sync-plugin',
+            sourceNodes: mockSourceNodes,
+            updateStrategy: 'sync',
+            sourceNodesContext: {
+              createNodeId: vi.fn(),
+              createContentDigest: vi.fn(),
+              options: {},
+              cacheDir: '/test',
+            },
+            store: mockStore as never,
+          };
+        }
+        // webhook-plugin uses default webhook strategy
+        return {
+          name: 'webhook-plugin',
+          sourceNodes: undefined,
+          updateStrategy: 'webhook',
+          sourceNodesContext: undefined,
+          store: undefined,
+        };
+      });
+
+      vi.mocked(defaultWebhookRegistry.getHandler).mockReturnValue({
+        pluginName: 'webhook-plugin',
+        handler: mockHandler,
+      });
+      vi.mocked(getWebhookHooks).mockReturnValue({});
+
+      const webhooks = [
+        createQueuedWebhook({ pluginName: 'sync-plugin' }),
+        createQueuedWebhook({ pluginName: 'webhook-plugin' }),
+      ];
+
+      await processWebhookBatch(webhooks);
+
+      // sync plugin should call sourceNodes
+      expect(mockSourceNodes).toHaveBeenCalledTimes(1);
+      // webhook plugin should call handler
+      expect(mockHandler).toHaveBeenCalledTimes(1);
+    });
+
+    it('should default to webhook strategy when plugin is not in registry', async () => {
+      const mockHandler = vi.fn().mockResolvedValue(undefined);
+
+      // Plugin not found in registry
+      vi.mocked(defaultPluginRegistry.get).mockReturnValue(undefined);
+      vi.mocked(defaultWebhookRegistry.getHandler).mockReturnValue({
+        pluginName: 'unknown-plugin',
+        handler: mockHandler,
+      });
+      vi.mocked(getWebhookHooks).mockReturnValue({});
+
+      const webhook = createQueuedWebhook({ pluginName: 'unknown-plugin' });
+
+      await processWebhookBatch([webhook]);
+
+      // Should use default webhook strategy and call handler
+      expect(mockHandler).toHaveBeenCalled();
+    });
+  });
 });

From 296b15fc262dbe8d233c2ddd0e76068a26d48a3f Mon Sep 17 00:00:00 2001
From: dawidurbanski <hi@dawidurbanski.com>
Date: Tue, 23 Dec 2025 14:45:53 +0100
Subject: [PATCH 44/46] fix(core): support scoped packages in webhook URLs

Update webhook URL pattern to properly extract scoped package names like
@universal-data-layer/plugin-source-contentful. Add URL decoding to handle
encoded @ symbols (%40) in webhook paths.
---
 packages/core/src/handlers/webhook.ts         |  8 ++-
 .../core/tests/unit/handlers/webhook.test.ts  | 69 +++++++++++++++++++
 2 files changed, 74 insertions(+), 3 deletions(-)

diff --git a/packages/core/src/handlers/webhook.ts b/packages/core/src/handlers/webhook.ts
index e30300b..6046499 100644
--- a/packages/core/src/handlers/webhook.ts
+++ b/packages/core/src/handlers/webhook.ts
@@ -20,8 +20,8 @@ import { defaultStore } from '@/nodes/defaultStore.js';
 /** URL path prefix for webhook endpoints */
 export const WEBHOOK_PATH_PREFIX = '/_webhooks/';
 
-/** Pattern for webhook URLs: /_webhooks/{plugin-name}/sync */
-const WEBHOOK_PATTERN = /^\/_webhooks\/([^/]+)\/sync(?:\?.*)?$/;
+/** Pattern for webhook URLs: /_webhooks/{plugin-name}/sync (supports scoped packages like @org/name) */
+const WEBHOOK_PATTERN = /^\/_webhooks\/(.+)\/sync(?:\?.*)?$/;
 
 /** Maximum request body size (1MB) */
 const MAX_BODY_SIZE = 1024 * 1024;
@@ -43,7 +43,9 @@ export function isWebhookRequest(url: string): boolean {
  * @returns The plugin name, or null if invalid format
  */
 export function getPluginFromWebhookUrl(url: string): string | null {
-  const match = url.match(WEBHOOK_PATTERN);
+  // URL-decode the path to handle encoded characters like %40 for @
+  const decodedUrl = decodeURIComponent(url);
+  const match = decodedUrl.match(WEBHOOK_PATTERN);
   if (!match) {
     return null;
   }
diff --git a/packages/core/tests/unit/handlers/webhook.test.ts b/packages/core/tests/unit/handlers/webhook.test.ts
index c84672c..5c8b5be 100644
--- a/packages/core/tests/unit/handlers/webhook.test.ts
+++ b/packages/core/tests/unit/handlers/webhook.test.ts
@@ -124,10 +124,39 @@ describe('getPluginFromWebhookUrl', () => {
     );
   });
 
+  it('should extract scoped package names from webhook URLs', () => {
+    expect(
+      getPluginFromWebhookUrl(
+        '/_webhooks/@universal-data-layer/plugin-source-contentful/sync'
+      )
+    ).toBe('@universal-data-layer/plugin-source-contentful');
+    expect(getPluginFromWebhookUrl('/_webhooks/@org/my-plugin/sync')).toBe(
+      '@org/my-plugin'
+    );
+    expect(getPluginFromWebhookUrl('/_webhooks/@scope/name/sync')).toBe(
+      '@scope/name'
+    );
+  });
+
+  it('should handle URL-encoded scoped package names', () => {
+    // %40 is the URL-encoded form of @
+    expect(
+      getPluginFromWebhookUrl(
+        '/_webhooks/%40universal-data-layer/plugin-source-contentful/sync'
+      )
+    ).toBe('@universal-data-layer/plugin-source-contentful');
+    expect(getPluginFromWebhookUrl('/_webhooks/%40org/my-plugin/sync')).toBe(
+      '@org/my-plugin'
+    );
+  });
+
   it('should handle query strings', () => {
     expect(getPluginFromWebhookUrl('/_webhooks/plugin/sync?foo=bar')).toBe(
       'plugin'
     );
+    expect(
+      getPluginFromWebhookUrl('/_webhooks/@org/my-plugin/sync?foo=bar')
+    ).toBe('@org/my-plugin');
   });
 
   it('should return null for invalid URLs', () => {
@@ -430,6 +459,46 @@ describe('webhookHandler', () => {
       consoleLogSpy.mockRestore();
     });
 
+    it('should queue webhook for scoped package names', async () => {
+      const consoleLogSpy = vi
+        .spyOn(console, 'log')
+        .mockImplementation(() => {});
+      let queuedWebhook: QueuedWebhook | undefined;
+
+      // Listen for enqueue
+      const originalEnqueue = queue.enqueue.bind(queue);
+      queue.enqueue = (webhook: QueuedWebhook) => {
+        queuedWebhook = webhook;
+        originalEnqueue(webhook);
+      };
+
+      registry.register(
+        '@universal-data-layer/plugin-source-contentful',
+        createTestWebhook()
+      );
+
+      const req = createMockRequest(
+        'POST',
+        '/_webhooks/@universal-data-layer/plugin-source-contentful/sync',
+        {
+          'content-type': 'application/json',
+        }
+      );
+      const res = createMockResponse();
+
+      emitBody(req, '{"test": true}');
+      await webhookHandler(req, res);
+
+      expect(res._statusCode).toBe(202);
+      expect(queuedWebhook).toBeDefined();
+      expect(queuedWebhook?.pluginName).toBe(
+        '@universal-data-layer/plugin-source-contentful'
+      );
+      expect(queuedWebhook?.body).toEqual({ test: true });
+
+      consoleLogSpy.mockRestore();
+    });
+
     it('should include headers in queued webhook', async () => {
       const consoleLogSpy = vi
         .spyOn(console, 'log')

From 8e868d8874e003657c41fe975fc661bdad963219 Mon Sep 17 00:00:00 2001
From: dawidurbanski <hi@dawidurbanski.com>
Date: Tue, 23 Dec 2025 15:05:05 +0100
Subject: [PATCH 45/46] refactor: move cache storage from .udl-cache to
 .udl/cache

Restructure cache directory to use `.udl/` as a parent directory for
all internal UDL files. This allows future expansion for storing other
library internals (logs, state, etc.) while keeping a single directory
to gitignore.

- Update FileCacheStorage to use .udl/cache/nodes.json
- Update FileSyncTokenStorage to use .udl/cache/contentful-sync-tokens.json
- Update all gitignore, prettierignore, and eslint ignore patterns
- Update documentation to reflect new paths
- Update all related tests
---
 .gitignore                                         |  2 +-
 .prettierignore                                    |  4 ++--
 docs/content/2.using-plugins/2.contentful.md       |  2 +-
 docs/content/6.reference/1.configuration.md        |  2 +-
 eslint.config.js                                   |  2 +-
 examples/nextjs/.gitignore                         |  4 ++--
 packages/core/src/cache/file-cache.ts              |  6 +++---
 packages/core/src/loader.ts                        |  4 ++--
 packages/core/tests/integration/loader.test.ts     |  6 +++---
 packages/core/tests/unit/cache/file-cache.test.ts  |  6 +++---
 packages/plugin-source-contentful/README.md        |  2 +-
 .../plugin-source-contentful/src/types/options.ts  |  2 +-
 .../plugin-source-contentful/src/utils/sync.ts     |  9 +++++++--
 .../tests/unit/utils/sync.test.ts                  | 14 +++++++-------
 14 files changed, 35 insertions(+), 30 deletions(-)

diff --git a/.gitignore b/.gitignore
index eb219ff..0346af0 100644
--- a/.gitignore
+++ b/.gitignore
@@ -19,7 +19,7 @@ packages/*/coverage/
 # Codegen
 generated/
 
-.udl-cache/
+.udl/
 .next/
 next-env.d.ts
 tsconfig.tsbuildinfo
diff --git a/.prettierignore b/.prettierignore
index d7c3e00..9001f5e 100644
--- a/.prettierignore
+++ b/.prettierignore
@@ -11,8 +11,8 @@ generated/
 .data/
 .cache/
 
-# Cache
-.udl-cache/
+# UDL internal files (cache, etc.)
+.udl/
 
 # Coverage reports
 coverage/
diff --git a/docs/content/2.using-plugins/2.contentful.md b/docs/content/2.using-plugins/2.contentful.md
index 9a4b23b..6f725ff 100644
--- a/docs/content/2.using-plugins/2.contentful.md
+++ b/docs/content/2.using-plugins/2.contentful.md
@@ -154,7 +154,7 @@ The plugin uses Contentful's Sync API for efficient incremental updates:
 1. **Initial sync**: Fetches all entries and assets
 2. **Delta sync**: Only fetches changes since the last sync
 
-Sync tokens are stored in `.udl-cache/contentful-sync-tokens.json` by default.
+Sync tokens are stored in `.udl/cache/contentful-sync-tokens.json` by default.
 
 ### Custom Token Storage
 
diff --git a/docs/content/6.reference/1.configuration.md b/docs/content/6.reference/1.configuration.md
index 0ad51f0..ac3149d 100644
--- a/docs/content/6.reference/1.configuration.md
+++ b/docs/content/6.reference/1.configuration.md
@@ -194,7 +194,7 @@ Control node caching behavior:
 
 | Value | Behavior |
 | ----- | -------- |
-| `undefined` (default) | File-based cache in `.udl-cache/nodes.json` |
+| `undefined` (default) | File-based cache in `.udl/cache/nodes.json` |
 | `false` | Disable caching entirely |
 | `CacheStorage` | Custom cache implementation |
 
diff --git a/eslint.config.js b/eslint.config.js
index 93e395c..0ffa546 100644
--- a/eslint.config.js
+++ b/eslint.config.js
@@ -61,7 +61,7 @@ export default [
       '**/coverage/**',
       '**/docs/**',
       '**/generated/**',
-      '**/.udl-cache/**',
+      '**/.udl/**',
       '**/.next/**',
     ],
   },
diff --git a/examples/nextjs/.gitignore b/examples/nextjs/.gitignore
index dede54c..b49b057 100644
--- a/examples/nextjs/.gitignore
+++ b/examples/nextjs/.gitignore
@@ -10,8 +10,8 @@ out/
 .env.local
 .env.*.local
 
-# Cache
-.udl-cache/
+# UDL (cache and other internal files)
+.udl/
 
 # TypeScript
 *.tsbuildinfo
diff --git a/packages/core/src/cache/file-cache.ts b/packages/core/src/cache/file-cache.ts
index dc7655d..624267c 100644
--- a/packages/core/src/cache/file-cache.ts
+++ b/packages/core/src/cache/file-cache.ts
@@ -41,12 +41,12 @@ function safeStringify(obj: unknown, indent?: number): string {
 /**
  * File-based cache storage implementation.
  *
- * Stores node data in `.udl-cache/nodes.json` by default.
+ * Stores node data in `.udl/cache/nodes.json` by default.
  * This is the default cache storage used when no custom implementation is provided.
  *
  * @example
  * ```typescript
- * // Use default path (.udl-cache/nodes.json in cwd)
+ * // Use default path (.udl/cache/nodes.json in cwd)
  * const cache = new FileCacheStorage();
  *
  * // Use custom base path
@@ -61,7 +61,7 @@ export class FileCacheStorage implements CacheStorage {
    * @param basePath - Base directory for cache files (default: process.cwd())
    */
   constructor(basePath: string = process.cwd()) {
-    this.filePath = join(basePath, '.udl-cache', 'nodes.json');
+    this.filePath = join(basePath, '.udl', 'cache', 'nodes.json');
   }
 
   /**
diff --git a/packages/core/src/loader.ts b/packages/core/src/loader.ts
index 4ee8ea7..2a88f6b 100644
--- a/packages/core/src/loader.ts
+++ b/packages/core/src/loader.ts
@@ -315,7 +315,7 @@ export interface UDLConfig {
   codegen?: CodegenConfig;
   /**
    * Cache storage for persisting nodes across server restarts.
-   * - `undefined` (default): Uses FileCacheStorage (stores in .udl-cache/nodes.json)
+   * - `undefined` (default): Uses FileCacheStorage (stores in .udl/cache/nodes.json)
    * - `false`: Disables caching entirely
    * - Custom `CacheStorage`: Use a custom cache implementation (e.g., Redis, SQLite)
    */
@@ -602,7 +602,7 @@ export interface LoadPluginsOptions {
   /**
    * Directory where cache files should be stored.
    * This should be the directory containing the udl.config.ts that specifies the plugins.
-   * Each plugin will store its cache in `cacheDir/.udl-cache/`.
+   * Each plugin will store its cache in `cacheDir/.udl/cache/`.
    */
   cacheDir?: string;
   /**
diff --git a/packages/core/tests/integration/loader.test.ts b/packages/core/tests/integration/loader.test.ts
index 6c58934..7bc3b9d 100644
--- a/packages/core/tests/integration/loader.test.ts
+++ b/packages/core/tests/integration/loader.test.ts
@@ -1384,7 +1384,7 @@ describe('loader integration tests', () => {
 
     it('should load and save nodes from cache when caching is enabled', async () => {
       const pluginDir = join(pluginsDir, 'cached-plugin');
-      const cacheDir = join(pluginDir, '.udl-cache');
+      const cacheDir = join(pluginDir, '.udl', 'cache');
       mkdirSync(pluginDir, { recursive: true });
 
       // Create a plugin that creates nodes
@@ -1459,7 +1459,7 @@ describe('loader integration tests', () => {
 
     it('should restore indexes from cache', async () => {
       const pluginDir = join(pluginsDir, 'cached-indexed-plugin');
-      const cacheDir = join(pluginDir, '.udl-cache');
+      const cacheDir = join(pluginDir, '.udl', 'cache');
       mkdirSync(pluginDir, { recursive: true });
 
       writeFileSync(
@@ -1522,7 +1522,7 @@ describe('loader integration tests', () => {
 
     it('should not cache when plugin config has cache: false', async () => {
       const pluginDir = join(pluginsDir, 'no-cache-plugin');
-      const cacheDir = join(pluginDir, '.udl-cache');
+      const cacheDir = join(pluginDir, '.udl', 'cache');
       mkdirSync(pluginDir, { recursive: true });
 
       writeFileSync(
diff --git a/packages/core/tests/unit/cache/file-cache.test.ts b/packages/core/tests/unit/cache/file-cache.test.ts
index ccd276d..0aefc62 100644
--- a/packages/core/tests/unit/cache/file-cache.test.ts
+++ b/packages/core/tests/unit/cache/file-cache.test.ts
@@ -33,7 +33,7 @@ vi.mock('node:fs', () => ({
 
 describe('FileCacheStorage', () => {
   const mockBasePath = '/test/project';
-  const expectedFilePath = '/test/project/.udl-cache/nodes.json';
+  const expectedFilePath = '/test/project/.udl/cache/nodes.json';
 
   beforeEach(() => {
     vi.clearAllMocks();
@@ -60,7 +60,7 @@ describe('FileCacheStorage', () => {
       vi.mocked(fs.existsSync).mockReturnValue(false);
       cache.load();
       expect(fs.existsSync).toHaveBeenCalledWith(
-        `${originalCwd}/.udl-cache/nodes.json`
+        `${originalCwd}/.udl/cache/nodes.json`
       );
     });
   });
@@ -204,7 +204,7 @@ describe('FileCacheStorage', () => {
 
       await cache.save(data);
 
-      expect(fs.mkdirSync).toHaveBeenCalledWith('/test/project/.udl-cache', {
+      expect(fs.mkdirSync).toHaveBeenCalledWith('/test/project/.udl/cache', {
         recursive: true,
       });
     });
diff --git a/packages/plugin-source-contentful/README.md b/packages/plugin-source-contentful/README.md
index 6fa0fbf..8348c56 100644
--- a/packages/plugin-source-contentful/README.md
+++ b/packages/plugin-source-contentful/README.md
@@ -65,7 +65,7 @@ The plugin uses Contentful's Sync API for efficient incremental updates:
 1. **Initial sync**: Fetches all entries and assets
 2. **Delta sync**: Only fetches changes since the last sync
 
-Sync tokens are stored in `.udl-cache/contentful-sync-tokens.json` by default. You can provide custom storage:
+Sync tokens are stored in `.udl/cache/contentful-sync-tokens.json` by default. You can provide custom storage:
 
 ```typescript
 {
diff --git a/packages/plugin-source-contentful/src/types/options.ts b/packages/plugin-source-contentful/src/types/options.ts
index 479237e..7de763b 100644
--- a/packages/plugin-source-contentful/src/types/options.ts
+++ b/packages/plugin-source-contentful/src/types/options.ts
@@ -107,7 +107,7 @@ export interface ContentfulPluginOptions {
   /**
    * Custom sync token storage implementation.
    * If not provided, uses the default file-based storage
-   * that stores tokens in `.udl-cache/contentful-sync-tokens.json`.
+   * that stores tokens in `.udl/cache/contentful-sync-tokens.json`.
    */
   syncTokenStorage?: SyncTokenStorage;
 }
diff --git a/packages/plugin-source-contentful/src/utils/sync.ts b/packages/plugin-source-contentful/src/utils/sync.ts
index 430d2d2..b11092f 100644
--- a/packages/plugin-source-contentful/src/utils/sync.ts
+++ b/packages/plugin-source-contentful/src/utils/sync.ts
@@ -33,7 +33,7 @@ export interface SyncResult {
 
 /**
  * Default file-based sync token storage.
- * Stores tokens in `.udl-cache/contentful-sync-tokens.json`.
+ * Stores tokens in `.udl/cache/contentful-sync-tokens.json`.
  */
 export class FileSyncTokenStorage implements SyncTokenStorage {
   private readonly filePath: string;
@@ -41,7 +41,12 @@ export class FileSyncTokenStorage implements SyncTokenStorage {
   private loaded = false;
 
   constructor(basePath: string = process.cwd()) {
-    this.filePath = join(basePath, '.udl-cache', 'contentful-sync-tokens.json');
+    this.filePath = join(
+      basePath,
+      '.udl',
+      'cache',
+      'contentful-sync-tokens.json'
+    );
   }
 
   private ensureLoaded(): void {
diff --git a/packages/plugin-source-contentful/tests/unit/utils/sync.test.ts b/packages/plugin-source-contentful/tests/unit/utils/sync.test.ts
index d6bad6b..cb91ca4 100644
--- a/packages/plugin-source-contentful/tests/unit/utils/sync.test.ts
+++ b/packages/plugin-source-contentful/tests/unit/utils/sync.test.ts
@@ -44,7 +44,7 @@ describe('FileSyncTokenStorage', () => {
 
       // Should check for file in default cwd path
       expect(mockExistsSync).toHaveBeenCalledWith(
-        expect.stringContaining('.udl-cache/contentful-sync-tokens.json')
+        expect.stringContaining('.udl/cache/contentful-sync-tokens.json')
       );
     });
 
@@ -55,7 +55,7 @@ describe('FileSyncTokenStorage', () => {
       storage.getSyncToken('test');
 
       expect(mockExistsSync).toHaveBeenCalledWith(
-        '/custom/path/.udl-cache/contentful-sync-tokens.json'
+        '/custom/path/.udl/cache/contentful-sync-tokens.json'
       );
     });
   });
@@ -124,7 +124,7 @@ describe('FileSyncTokenStorage', () => {
       await storage.setSyncToken('space1:master', 'newtoken');
 
       expect(mockWriteFileSync).toHaveBeenCalledWith(
-        '/base/.udl-cache/contentful-sync-tokens.json',
+        '/base/.udl/cache/contentful-sync-tokens.json',
         JSON.stringify({ 'space1:master': 'newtoken' }, null, 2)
       );
     });
@@ -138,7 +138,7 @@ describe('FileSyncTokenStorage', () => {
 
       await storage.setSyncToken('space1:master', 'newtoken');
 
-      expect(mockMkdirSync).toHaveBeenCalledWith('/base/.udl-cache', {
+      expect(mockMkdirSync).toHaveBeenCalledWith('/base/.udl/cache', {
         recursive: true,
       });
     });
@@ -164,7 +164,7 @@ describe('FileSyncTokenStorage', () => {
       await storage.setSyncToken('new:key', 'newtoken');
 
       expect(mockWriteFileSync).toHaveBeenCalledWith(
-        '/base/.udl-cache/contentful-sync-tokens.json',
+        '/base/.udl/cache/contentful-sync-tokens.json',
         JSON.stringify(
           { existing: 'existingtoken', 'new:key': 'newtoken' },
           null,
@@ -188,7 +188,7 @@ describe('FileSyncTokenStorage', () => {
       await storage.clearSyncToken('space1:master');
 
       expect(mockWriteFileSync).toHaveBeenCalledWith(
-        '/base/.udl-cache/contentful-sync-tokens.json',
+        '/base/.udl/cache/contentful-sync-tokens.json',
         JSON.stringify({ 'space2:master': 'token2' }, null, 2)
       );
     });
@@ -201,7 +201,7 @@ describe('FileSyncTokenStorage', () => {
       await storage.clearSyncToken('nonexistent');
 
       expect(mockWriteFileSync).toHaveBeenCalledWith(
-        '/base/.udl-cache/contentful-sync-tokens.json',
+        '/base/.udl/cache/contentful-sync-tokens.json',
         JSON.stringify({ other: 'token' }, null, 2)
       );
     });

From f2ca911714da7db7603dbaf53f56382cc760324d Mon Sep 17 00:00:00 2001
From: dawidurbanski <hi@dawidurbanski.com>
Date: Tue, 23 Dec 2025 15:06:17 +0100
Subject: [PATCH 46/46] chore: update turbo to version 2.7.1

---
 package-lock.json | 59 ++++++++++++++++++++++-------------------------
 package.json      |  2 +-
 2 files changed, 29 insertions(+), 32 deletions(-)

diff --git a/package-lock.json b/package-lock.json
index 16d60fa..f8bac63 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -31,7 +31,7 @@
         "prettier": "^3.6.2",
         "tsc-alias": "^1.8.16",
         "tsc-watch": "^7.1.1",
-        "turbo": "^2.7.0",
+        "turbo": "^2.7.1",
         "typescript": "^5.9.2",
         "vitest": "^3.2.4"
       },
@@ -10947,27 +10947,27 @@
       }
     },
     "node_modules/turbo": {
-      "version": "2.7.0",
-      "resolved": "https://registry.npmjs.org/turbo/-/turbo-2.7.0.tgz",
-      "integrity": "sha512-1dUGwi6cSSVZts1BwJa/Gh7w5dPNNGsNWZEAuRKxXWME44hTKWpQZrgiPnqMc5jJJOovzPK5N6tL+PHYRYL5Wg==",
+      "version": "2.7.1",
+      "resolved": "https://registry.npmjs.org/turbo/-/turbo-2.7.1.tgz",
+      "integrity": "sha512-zAj9jGc7VDvuAo/5Jbos4QTtWz9uUpkMhMKGyTjDJkx//hdL2bM31qQoJSAbU+7JyK5vb0LPzpwf6DUt3zayqg==",
       "dev": true,
       "license": "MIT",
       "bin": {
         "turbo": "bin/turbo"
       },
       "optionalDependencies": {
-        "turbo-darwin-64": "2.7.0",
-        "turbo-darwin-arm64": "2.7.0",
-        "turbo-linux-64": "2.7.0",
-        "turbo-linux-arm64": "2.7.0",
-        "turbo-windows-64": "2.7.0",
-        "turbo-windows-arm64": "2.7.0"
+        "turbo-darwin-64": "2.7.1",
+        "turbo-darwin-arm64": "2.7.1",
+        "turbo-linux-64": "2.7.1",
+        "turbo-linux-arm64": "2.7.1",
+        "turbo-windows-64": "2.7.1",
+        "turbo-windows-arm64": "2.7.1"
       }
     },
     "node_modules/turbo-darwin-64": {
-      "version": "2.7.0",
-      "resolved": "https://registry.npmjs.org/turbo-darwin-64/-/turbo-darwin-64-2.7.0.tgz",
-      "integrity": "sha512-gwqL7cJOSYrV/jNmhXM8a2uzSFn7GcUASOuen6OgmUsafUj9SSWcgXZ/q0w9hRoL917hpidkdI//UpbxbZbwwg==",
+      "version": "2.7.1",
+      "resolved": "https://registry.npmjs.org/turbo-darwin-64/-/turbo-darwin-64-2.7.1.tgz",
+      "integrity": "sha512-EaA7UfYujbY9/Ku0WqPpvfctxm91h9LF7zo8vjielz+omfAPB54Si+ADmUoBczBDC6RoLgbURC3GmUW2alnjJg==",
       "cpu": [
         "x64"
       ],
@@ -10979,9 +10979,9 @@
       ]
     },
     "node_modules/turbo-darwin-arm64": {
-      "version": "2.7.0",
-      "resolved": "https://registry.npmjs.org/turbo-darwin-arm64/-/turbo-darwin-arm64-2.7.0.tgz",
-      "integrity": "sha512-f3F5DYOnfE6lR6v/rSld7QGZgartKsnlIYY7jcF/AA7Wz27za9XjxMHzb+3i4pvRhAkryFgf2TNq7eCFrzyTpg==",
+      "version": "2.7.1",
+      "resolved": "https://registry.npmjs.org/turbo-darwin-arm64/-/turbo-darwin-arm64-2.7.1.tgz",
+      "integrity": "sha512-/pWGSygtBugd7sKQOeMm+jKY3qN1vyB0RiHBM6bN/6qUOo2VHo8IQwBTIaSgINN4Ue6fzEU+WfePNvonSU9yXw==",
       "cpu": [
         "arm64"
       ],
@@ -10993,9 +10993,9 @@
       ]
     },
     "node_modules/turbo-linux-64": {
-      "version": "2.7.0",
-      "resolved": "https://registry.npmjs.org/turbo-linux-64/-/turbo-linux-64-2.7.0.tgz",
-      "integrity": "sha512-KsC+UuKlhjCL+lom10/IYoxUsdhJOsuEki72YSr7WGYUSRihcdJQnaUyIDTlm0nPOb+gVihVNBuVP4KsNg1UnA==",
+      "version": "2.7.1",
+      "resolved": "https://registry.npmjs.org/turbo-linux-64/-/turbo-linux-64-2.7.1.tgz",
+      "integrity": "sha512-Y5H11mdhASw/dJuRFyGtTCDFX5/MPT73EKsVEiHbw5MkFc77lx3nMc5L/Q7bKEhef/vYJAsAb61QuHsB6qdP8Q==",
       "cpu": [
         "x64"
       ],
@@ -11007,9 +11007,9 @@
       ]
     },
     "node_modules/turbo-linux-arm64": {
-      "version": "2.7.0",
-      "resolved": "https://registry.npmjs.org/turbo-linux-arm64/-/turbo-linux-arm64-2.7.0.tgz",
-      "integrity": "sha512-1tjIYULeJtpmE/ovoI9qPBFJCtUEM7mYfeIMOIs4bXR6t/8u+rHPwr3j+vRHcXanIc42V1n3Pz52VqmJtIAviw==",
+      "version": "2.7.1",
+      "resolved": "https://registry.npmjs.org/turbo-linux-arm64/-/turbo-linux-arm64-2.7.1.tgz",
+      "integrity": "sha512-L/r77jD7cqIEXoyu2LGBUrTY5GJSi/XcGLsQ2nZ/fefk6x3MpljTvwsXUVG1BUkiBPc4zaKRj6yGyWMo5MbLxQ==",
       "cpu": [
         "arm64"
       ],
@@ -11021,9 +11021,9 @@
       ]
     },
     "node_modules/turbo-windows-64": {
-      "version": "2.7.0",
-      "resolved": "https://registry.npmjs.org/turbo-windows-64/-/turbo-windows-64-2.7.0.tgz",
-      "integrity": "sha512-KThkAeax46XiH+qICCQm7R8V2pPdeTTP7ArCSRrSLqnlO75ftNm8Ljx4VAllwIZkILrq/GDM8PlyhZdPeUdDxQ==",
+      "version": "2.7.1",
+      "resolved": "https://registry.npmjs.org/turbo-windows-64/-/turbo-windows-64-2.7.1.tgz",
+      "integrity": "sha512-rkeuviXZ/1F7lCare7TNKvYtT/SH9dZR55FAMrxrFRh88b+ZKwlXEBfq5/1OctEzRUo/VLIm+s5LJMOEy+QshA==",
       "cpu": [
         "x64"
       ],
@@ -11035,9 +11035,9 @@
       ]
     },
     "node_modules/turbo-windows-arm64": {
-      "version": "2.7.0",
-      "resolved": "https://registry.npmjs.org/turbo-windows-arm64/-/turbo-windows-arm64-2.7.0.tgz",
-      "integrity": "sha512-kzI6rsQ3Ejs+CkM9HEEP3Z4h5YMCRxwIlQXFQmgXSG3BIgorCkRF2Xr7iQ2i9AGwY/6jbiAYeJbvi3yCp+noFw==",
+      "version": "2.7.1",
+      "resolved": "https://registry.npmjs.org/turbo-windows-arm64/-/turbo-windows-arm64-2.7.1.tgz",
+      "integrity": "sha512-1rZk9htm3+iP/rWCf/h4/DFQey9sMs2TJPC4T5QQfwqAdMWsphgrxBuFqHdxczlbBCgbWNhVw0CH2bTxe1/GFg==",
       "cpu": [
         "arm64"
       ],
@@ -11937,9 +11937,6 @@
       "bin": {
         "udl-next": "bin/udl-next.js"
       },
-      "devDependencies": {
-        "universal-data-layer": "*"
-      },
       "peerDependencies": {
         "next": ">=13.0.0",
         "universal-data-layer": "^1.0.6"
diff --git a/package.json b/package.json
index 1ebef85..ced2bb9 100644
--- a/package.json
+++ b/package.json
@@ -56,7 +56,7 @@
     "prettier": "^3.6.2",
     "tsc-alias": "^1.8.16",
     "tsc-watch": "^7.1.1",
-    "turbo": "^2.7.0",
+    "turbo": "^2.7.1",
     "typescript": "^5.9.2",
     "vitest": "^3.2.4"
   },