@pixelbyte-software/pixcode 1.42.5 → 1.43.0

package/server/services/public-api-manifest.js

@@ -13,6 +13,7 @@ const API_GROUPS = [
   { id: 'diagnostics', title: 'Diagnostics', basePath: '/api/diagnostics', scopes: ['diagnostics:read'] },
   { id: 'remote', title: 'Remote connection', basePath: '/api/remote', scopes: ['remote:read', 'remote:write'] },
   { id: 'telegram', title: 'Telegram control', basePath: '/api/telegram', scopes: ['telegram:read', 'telegram:write'] },
+  { id: 'webhooks', title: 'Outbound webhooks', basePath: '/api/webhooks', scopes: ['webhooks:read', 'webhooks:write'] },
   { id: 'plugins', title: 'Plugins and MCP tools', basePath: '/api/plugins', scopes: ['plugins:read', 'plugins:write'] },
 ];
 
@@ -48,6 +49,103 @@ export function buildPublicApiManifest({ baseUrl = '' } = {}) {
         title: 'Fetch diagnostics bundle',
         curl: `curl -H "X-API-Key: px_your_key" ${origin || 'http://127.0.0.1:3001'}/api/diagnostics/bundle`,
       },
+      {
+        title: 'Read the mobile remote control room',
+        curl: `curl -H "X-API-Key: px_your_key" ${origin || 'http://127.0.0.1:3001'}/api/remote/control-room`,
+      },
+      {
+        title: 'Register an outbound webhook',
+        curl: `curl -X POST -H "Content-Type: application/json" -H "X-API-Key: px_your_key" -d '{"name":"CI listener","url":"https://example.com/pixcode","events":["run.completed","approval.needed"]}' ${origin || 'http://127.0.0.1:3001'}/api/webhooks`,
+      },
+    ],
+  };
+}
+
+export function buildTypeScriptSdkStarter({ baseUrl = '' } = {}) {
+  const origin = String(baseUrl || 'http://127.0.0.1:3001').replace(/\/+$/, '');
+  return `export type PixcodeRun = {
+  id: string;
+  workflowId: string;
+  status: 'queued' | 'running' | 'completed' | 'failed' | 'canceled';
+};
+
+export class PixcodeClient {
+  constructor(
+    private readonly apiKey: string,
+    private readonly baseUrl = '${origin}',
+  ) {}
+
+  private async request<T>(path: string, init: RequestInit = {}): Promise<T> {
+    const response = await fetch(new URL(path, this.baseUrl), {
+      ...init,
+      headers: {
+        'Content-Type': 'application/json',
+        'X-API-Key': this.apiKey,
+        ...(init.headers || {}),
+      },
+    });
+    if (!response.ok) throw new Error(\`Pixcode API \${response.status}: \${await response.text()}\`);
+    return response.json() as Promise<T>;
+  }
+
+  projects() {
+    return this.request<{ projects: unknown[] }>('/api/projects');
+  }
+
+  controlRoom() {
+    return this.request<{ success: true; controlRoom: unknown }>('/api/remote/control-room');
+  }
+
+  approvals() {
+    return this.request<{ pendingApprovals: unknown[] }>('/api/orchestration/workflows/approvals');
+  }
+
+  decideApproval(approvalId: string, allow: boolean) {
+    return this.request(\`/api/orchestration/workflows/approvals/\${encodeURIComponent(approvalId)}\`, {
+      method: 'POST',
+      body: JSON.stringify({ allow, source: 'api' }),
+    });
+  }
+
+  startWorkflow(workflowId: string, input: string, metadata: Record<string, unknown> = {}) {
+    return this.request<PixcodeRun>(\`/api/orchestration/workflows/\${encodeURIComponent(workflowId)}/runs\`, {
+      method: 'POST',
+      body: JSON.stringify({ input, metadata }),
+    });
+  }
+}
+`;
+}
+
+export function buildCurlCookbook({ baseUrl = '' } = {}) {
+  const origin = String(baseUrl || 'http://127.0.0.1:3001').replace(/\/+$/, '');
+  return {
+    title: 'Pixcode Public API Cookbook',
+    variables: {
+      PIXCODE_URL: origin,
+      PIXCODE_API_KEY: 'px_your_key',
+    },
+    examples: [
+      {
+        title: 'List projects',
+        command: `curl -H "X-API-Key: $PIXCODE_API_KEY" "$PIXCODE_URL/api/projects"`,
+      },
+      {
+        title: 'Read the mobile control room',
+        command: `curl -H "X-API-Key: $PIXCODE_API_KEY" "$PIXCODE_URL/api/remote/control-room"`,
+      },
+      {
+        title: 'List pending approvals',
+        command: `curl -H "X-API-Key: $PIXCODE_API_KEY" "$PIXCODE_URL/api/orchestration/workflows/approvals"`,
+      },
+      {
+        title: 'Approve a pending action',
+        command: `curl -X POST -H "Content-Type: application/json" -H "X-API-Key: $PIXCODE_API_KEY" -d '{"allow":true,"source":"api"}' "$PIXCODE_URL/api/orchestration/workflows/approvals/approval_id"`,
+      },
+      {
+        title: 'Create a webhook',
+        command: `curl -X POST -H "Content-Type: application/json" -H "X-API-Key: $PIXCODE_API_KEY" -d '{"name":"CI listener","url":"https://example.com/pixcode","events":["run.completed","run.failed","approval.needed"]}' "$PIXCODE_URL/api/webhooks"`,
+      },
     ],
   };
 }

package/server/services/telegram/control-center.js

@@ -37,6 +37,10 @@ const CONTROL_COMMANDS = new Set([
   '/workflows',
   '/orchestration',
   '/runs',
+  '/approvals',
+  '/controlroom',
+  '/control-room',
+  '/webhooks',
   '/sessions',
   '/newchat',
   '/tasks',
@@ -203,6 +207,8 @@ function mainMenuKeyboard(lang) {
     [button(t(lang, 'control.button.projects'), 'projects'), button(t(lang, 'control.button.provider'), 'providers')],
     [button(t(lang, 'control.button.models'), 'models'), button(t(lang, 'control.button.workflows'), 'workflows')],
     [button(t(lang, 'control.button.tasks'), 'tasks'), button(t(lang, 'control.button.runs'), 'runs')],
+    [button(t(lang, 'control.button.approvals'), 'approvals'), button(t(lang, 'control.button.controlRoom'), 'control_room')],
+    [button(t(lang, 'control.button.webhooks'), 'webhooks')],
     [button(t(lang, 'control.button.sessions'), 'sessions'), button(t(lang, 'control.button.newChat'), 'new_chat')],
     [button(t(lang, 'control.button.install'), 'install_menu'), button(t(lang, 'control.button.auth'), 'auth_menu')],
     [button(t(lang, 'control.button.settings'), 'settings')],
@@ -338,6 +344,82 @@ async function showRuns({ bot, chatId, link, editMessageId }) {
   });
 }
 
+async function showApprovalQueue({ bot, chatId, link, editMessageId }) {
+  const lang = languageFor(link);
+  const data = await localApi(link.user_id, '/api/orchestration/workflows/approvals');
+  const approvals = Array.isArray(data?.pendingApprovals) ? data.pendingApprovals : [];
+  if (approvals.length === 0) {
+    await send(bot, chatId, t(lang, 'control.noApprovals'), { editMessageId });
+    return;
+  }
+
+  const keyboard = [];
+  const lines = approvals.slice(0, 8).map((approval, index) => {
+    const label = compact(approval.summary || approval.reason || approval.id, 70);
+    keyboard.push([
+      button(t(lang, 'control.button.approve'), 'approval_decide', { approvalId: approval.id, allow: true }),
+      button(t(lang, 'control.button.deny'), 'approval_decide', { approvalId: approval.id, allow: false }),
+    ]);
+    return `${index + 1}. ${label}\nRun: ${approval.runId}`;
+  });
+  keyboard.push([button(t(lang, 'control.button.refresh'), 'approvals'), button(t(lang, 'control.button.mainMenu'), 'menu')]);
+  await send(bot, chatId, `${t(lang, 'control.approvalQueue')}\n\n${lines.join('\n\n')}`, {
+    editMessageId,
+    reply_markup: { inline_keyboard: keyboard },
+  });
+}
+
+async function showControlRoom({ bot, chatId, link, editMessageId }) {
+  const lang = languageFor(link);
+  const data = await localApi(link.user_id, '/api/remote/control-room');
+  const snapshot = data?.controlRoom || data;
+  const projects = Array.isArray(snapshot?.projects) ? snapshot.projects : [];
+  const totals = snapshot?.totals || {};
+  const lines = projects.map((project, index) => [
+    `${index + 1}. ${compact(project.name || project.id, 44)}`,
+    `Runs: ${project.activeRunCount || 0} active / ${project.failedRunCount || 0} failed`,
+    `Approvals: ${project.pendingApprovalCount || 0}`,
+  ].join('\n'));
+  await send(bot, chatId, [
+    t(lang, 'control.controlRoomTitle'),
+    '',
+    `Projects: ${totals.projects || 0}`,
+    `Active runs: ${totals.activeRuns || 0}`,
+    `Pending approvals: ${totals.pendingApprovals || 0}`,
+    '',
+    lines.join('\n\n') || t(lang, 'control.noProjects'),
+  ].join('\n'), {
+    editMessageId,
+    reply_markup: {
+      inline_keyboard: [
+        [button(t(lang, 'control.button.approvals'), 'approvals'), button(t(lang, 'control.button.runs'), 'runs')],
+        [button(t(lang, 'control.button.mainMenu'), 'menu')],
+      ],
+    },
+  });
+}
+
+async function showWebhookMenu({ bot, chatId, link, editMessageId }) {
+  const lang = languageFor(link);
+  const data = await localApi(link.user_id, '/api/webhooks');
+  const webhooks = Array.isArray(data?.webhooks) ? data.webhooks : [];
+  const lines = webhooks.slice(0, 10).map((webhook, index) => (
+    `${index + 1}. ${webhook.enabled ? 'on' : 'off'} ${compact(webhook.name || webhook.url, 50)}\n${compact(webhook.events?.join(', ') || webhook.url, 90)}`
+  ));
+  await send(bot, chatId, [
+    t(lang, 'control.webhookTitle'),
+    '',
+    lines.join('\n\n') || t(lang, 'control.noWebhooks'),
+  ].join('\n'), {
+    editMessageId,
+    reply_markup: {
+      inline_keyboard: [
+        [button(t(lang, 'control.button.refresh'), 'webhooks'), button(t(lang, 'control.button.mainMenu'), 'menu')],
+      ],
+    },
+  });
+}
+
 async function showSessions({ bot, chatId, link, editMessageId }) {
   const lang = languageFor(link);
   const state = getState(link.user_id);
@@ -783,6 +865,18 @@ async function handleCommand({ bot, chatId, link, text }) {
     await showRuns({ bot, chatId, link });
     return true;
   }
+  if (command === '/approvals') {
+    await showApprovalQueue({ bot, chatId, link });
+    return true;
+  }
+  if (command === '/controlroom' || command === '/control-room') {
+    await showControlRoom({ bot, chatId, link });
+    return true;
+  }
+  if (command === '/webhooks') {
+    await showWebhookMenu({ bot, chatId, link });
+    return true;
+  }
   if (command === '/sessions') {
     await showSessions({ bot, chatId, link });
     return true;
@@ -927,6 +1021,9 @@ export async function handleTelegramControlCallback({ bot, query, link }) {
   if (action === 'models_refresh') return showModelMenu({ bot, chatId, link, refresh: true, editMessageId });
   if (action === 'workflows') return showWorkflowMenu({ bot, chatId, link, editMessageId });
   if (action === 'runs') return showRuns({ bot, chatId, link, editMessageId });
+  if (action === 'approvals') return showApprovalQueue({ bot, chatId, link, editMessageId });
+  if (action === 'control_room') return showControlRoom({ bot, chatId, link, editMessageId });
+  if (action === 'webhooks') return showWebhookMenu({ bot, chatId, link, editMessageId });
   if (action === 'sessions') return showSessions({ bot, chatId, link, editMessageId });
   if (action === 'new_chat') return startNewChat({ bot, chatId, link, editMessageId });
   if (action === 'tasks') return showTaskMasterTasks({ bot, chatId, link, editMessageId });
@@ -989,6 +1086,22 @@ export async function handleTelegramControlCallback({ bot, query, link }) {
     await send(bot, chatId, t(languageFor(link), 'control.runStatus', { runId: run.id, status: run.status }), { editMessageId });
     return;
   }
+  if (action === 'approval_decide') {
+    const result = await localApi(link.user_id, `/api/orchestration/workflows/approvals/${encodeURIComponent(payload.approvalId)}`, {
+      method: 'POST',
+      body: {
+        allow: payload.allow === true,
+        source: 'telegram',
+      },
+    });
+    const lang = languageFor(link);
+    await send(bot, chatId, t(lang, 'control.approvalDecided', {
+      approvalId: payload.approvalId,
+      status: payload.allow === true ? 'approved' : 'denied',
+      runId: result?.runId || '',
+    }), { editMessageId });
+    return showApprovalQueue({ bot, chatId, link });
+  }
   if (action === 'task_run') return runTaskMasterTask({ bot, chatId, link, taskId: payload.taskId });
   if (action === 'install_provider') return startCliInstall({ bot, chatId, link, provider: payload.provider });
   if (action === 'auth_provider') {

package/server/services/telegram/translations.js

@@ -18,7 +18,7 @@ const EN = {
   'bridge.queued': '📨 Message forwarded to your latest session. I will reply when the agent responds.',
   'bridge.disabled': 'Message bridge is disabled. Enable it in Pixcode → Settings → Telegram.',
   'control.menu': 'Pixcode Telegram control center',
-  'control.help': 'Commands: /menu, /projects, /provider, /model, /workflows, /runs, /sessions, /newchat, /tasks, /task <id>, /chat <prompt>, /workflow <prompt>, /install, /auth, /settings, /progress final|steps|errors|all, /control on|off.',
+  'control.help': 'Commands: /menu, /projects, /provider, /model, /workflows, /runs, /approvals, /control-room, /webhooks, /sessions, /newchat, /tasks, /task <id>, /chat <prompt>, /workflow <prompt>, /install, /auth, /settings, /progress final|steps|errors|all, /control on|off.',
   'control.examples': 'Examples:\n/chat summarize this project\n/chat fix the last error\n/workflow review the current changes\n/settings to change language and progress mode',
   'control.unknownCommand': 'I do not know that command yet. Here are the available Pixcode commands:',
   'control.onboarding': 'How to start:\n/projects to pick a project\n/provider to pick the CLI\n/model to choose the model\n/chat <prompt> to run the current agent\n/workflow <prompt> to run orchestration\n/help to see all commands',
@@ -32,6 +32,9 @@ const EN = {
   'control.button.models': 'Models',
   'control.button.workflows': 'Workflows',
   'control.button.runs': 'Runs',
+  'control.button.approvals': 'Approvals',
+  'control.button.controlRoom': 'Control room',
+  'control.button.webhooks': 'Webhooks',
   'control.button.sessions': 'Sessions',
   'control.button.newChat': 'New chat',
   'control.button.tasks': 'Tasks',
@@ -51,6 +54,8 @@ const EN = {
   'control.button.mainMenu': 'Main menu',
   'control.button.cancelRun': 'Cancel run',
   'control.button.refresh': 'Refresh',
+  'control.button.approve': 'Approve',
+  'control.button.deny': 'Deny',
   'control.noProjects': 'No Pixcode projects were found yet. Add/open a project in Pixcode first.',
   'control.pickProject': 'Pick the project Telegram should control:',
   'control.pickProvider': 'Pick the CLI provider Telegram should use:',
@@ -58,6 +63,12 @@ const EN = {
   'control.pickWorkflow': 'Pick an orchestration workflow:',
   'control.noRuns': 'No orchestration runs yet.',
   'control.recentRuns': 'Recent orchestration runs:',
+  'control.approvalQueue': 'Pending approval queue:',
+  'control.noApprovals': 'No pending approvals.',
+  'control.approvalDecided': 'Approval {{approvalId}} {{status}}.\nRun: {{runId}}',
+  'control.controlRoomTitle': 'Multi-project control room',
+  'control.webhookTitle': 'Outbound webhooks',
+  'control.noWebhooks': 'No webhooks are configured yet.',
   'control.noSessions': 'No sessions were found for the selected project.',
   'control.recentSessions': 'Recent sessions:',
   'control.newChatReady': 'New chat is ready. Send the prompt you want to run.',
@@ -115,7 +126,7 @@ const TR = {
   'bridge.queued': '📨 Mesaj son oturumuna iletildi. Ajan cevap verince sana yazacağım.',
   'bridge.disabled': 'Mesaj köprüsü kapalı. Pixcode → Ayarlar → Telegram\'dan açabilirsin.',
   'control.menu': 'Pixcode Telegram kontrol merkezi',
-  'control.help': 'Komutlar: /menu, /projects, /provider, /model, /workflows, /runs, /sessions, /newchat, /tasks, /task <id>, /chat <prompt>, /workflow <prompt>, /install, /auth, /settings, /progress final|steps|errors|all, /control on|off.',
+  'control.help': 'Komutlar: /menu, /projects, /provider, /model, /workflows, /runs, /approvals, /control-room, /webhooks, /sessions, /newchat, /tasks, /task <id>, /chat <prompt>, /workflow <prompt>, /install, /auth, /settings, /progress final|steps|errors|all, /control on|off.',
   'control.examples': 'Örnekler:\n/chat bu projeyi özetle\n/chat son hatayı düzelt\n/workflow mevcut değişiklikleri incele\n/settings ile dil ve ilerleme modunu değiştir',
   'control.unknownCommand': 'Bu komutu henüz tanımıyorum. Kullanabileceğin Pixcode komutları:',
   'control.onboarding': 'Nasıl başlarsın:\n/projects ile proje seç\n/provider ile CLI seç\n/model ile modeli seç\n/chat <prompt> ile ajanı çalıştır\n/workflow <prompt> ile orkestrasyon başlat\n/help ile tüm komutları gör',
@@ -129,6 +140,9 @@ const TR = {
   'control.button.models': 'Modeller',
   'control.button.workflows': 'İş akışları',
   'control.button.runs': 'Çalışmalar',
+  'control.button.approvals': 'Onaylar',
+  'control.button.controlRoom': 'Kontrol odası',
+  'control.button.webhooks': 'Webhooklar',
   'control.button.sessions': 'Oturumlar',
   'control.button.newChat': 'Yeni sohbet',
   'control.button.tasks': 'Görevler',
@@ -148,6 +162,8 @@ const TR = {
   'control.button.mainMenu': 'Ana menü',
   'control.button.cancelRun': 'Çalışmayı iptal et',
   'control.button.refresh': 'Yenile',
+  'control.button.approve': 'Onayla',
+  'control.button.deny': 'Reddet',
   'control.noProjects': 'Henüz Pixcode projesi bulunamadı. Önce Pixcode içinde proje ekle/aç.',
   'control.pickProject': 'Telegramın kontrol edeceği projeyi seç:',
   'control.pickProvider': 'Telegramın kullanacağı CLI sağlayıcısını seç:',
@@ -155,6 +171,12 @@ const TR = {
   'control.pickWorkflow': 'Bir orkestrasyon iş akışı seç:',
   'control.noRuns': 'Henüz orkestrasyon çalışması yok.',
   'control.recentRuns': 'Son orkestrasyon çalışmaları:',
+  'control.approvalQueue': 'Bekleyen onay kuyruğu:',
+  'control.noApprovals': 'Bekleyen onay yok.',
+  'control.approvalDecided': '{{approvalId}} onayı {{status}}.\nÇalışma: {{runId}}',
+  'control.controlRoomTitle': 'Çok projeli kontrol odası',
+  'control.webhookTitle': 'Dış webhooklar',
+  'control.noWebhooks': 'Henüz webhook yapılandırılmadı.',
   'control.noSessions': 'Seçili proje için oturum bulunamadı.',
   'control.recentSessions': 'Son oturumlar:',
   'control.newChatReady': 'Yeni sohbet hazır. Çalıştırmak istediğin promptu gönder.',

package/server/services/webhooks.js

@@ -0,0 +1,216 @@
+import crypto from 'node:crypto';
+
+import { appConfigDb } from '../database/db.js';
+
+const CONFIG_KEY = 'webhooks';
+const MAX_ATTEMPTS = 2;
+
+export const PIXCODE_WEBHOOK_EVENT_TYPES = [
+  'run.started',
+  'run.completed',
+  'run.failed',
+  'run.canceled',
+  'file.changed',
+  'approval.needed',
+  'approval.resolved',
+  'live_view.started',
+  'live_view.failed',
+];
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function readStore() {
+  const raw = appConfigDb.get(CONFIG_KEY);
+  if (!raw) return { version: 1, webhooks: [] };
+  try {
+    const parsed = JSON.parse(raw);
+    return {
+      version: 1,
+      webhooks: Array.isArray(parsed?.webhooks) ? parsed.webhooks.map(normalizeWebhook).filter(Boolean) : [],
+    };
+  } catch {
+    return { version: 1, webhooks: [] };
+  }
+}
+
+function writeStore(store) {
+  appConfigDb.set(CONFIG_KEY, JSON.stringify({
+    version: 1,
+    webhooks: store.webhooks.map(normalizeWebhook).filter(Boolean),
+  }));
+}
+
+function normalizeUrl(value) {
+  const raw = typeof value === 'string' ? value.trim() : '';
+  if (!raw) throw new Error('Webhook URL is required.');
+  const parsed = new URL(raw);
+  if (!['http:', 'https:'].includes(parsed.protocol)) {
+    throw new Error('Webhook URL must use http or https.');
+  }
+  parsed.hash = '';
+  return parsed.toString();
+}
+
+function normalizeEvents(events) {
+  if (!Array.isArray(events) || events.length === 0) return ['run.completed', 'run.failed', 'approval.needed'];
+  return Array.from(new Set(events
+    .filter((event) => PIXCODE_WEBHOOK_EVENT_TYPES.includes(event))
+  )).sort();
+}
+
+function normalizeWebhook(input) {
+  if (!input || typeof input !== 'object') return null;
+  const id = typeof input.id === 'string' && input.id ? input.id : crypto.randomUUID();
+  const name = typeof input.name === 'string' && input.name.trim() ? input.name.trim() : 'Pixcode webhook';
+  const url = normalizeUrl(input.url);
+  const secret = typeof input.secret === 'string' && input.secret.trim()
+    ? input.secret.trim()
+    : crypto.randomBytes(24).toString('hex');
+  return {
+    id,
+    name,
+    url,
+    secret,
+    enabled: input.enabled !== false,
+    events: normalizeEvents(input.events),
+    createdAt: typeof input.createdAt === 'string' ? input.createdAt : nowIso(),
+    updatedAt: typeof input.updatedAt === 'string' ? input.updatedAt : nowIso(),
+    lastDelivery: input.lastDelivery && typeof input.lastDelivery === 'object' ? input.lastDelivery : null,
+  };
+}
+
+function publicWebhook(webhook) {
+  return {
+    id: webhook.id,
+    name: webhook.name,
+    url: webhook.url,
+    enabled: webhook.enabled,
+    events: webhook.events,
+    createdAt: webhook.createdAt,
+    updatedAt: webhook.updatedAt,
+    secretPresent: Boolean(webhook.secret),
+    lastDelivery: webhook.lastDelivery,
+  };
+}
+
+export function listWebhooks() {
+  return readStore().webhooks.map(publicWebhook);
+}
+
+export function upsertWebhook(input = {}) {
+  const store = readStore();
+  const existing = typeof input.id === 'string'
+    ? store.webhooks.find((webhook) => webhook.id === input.id)
+    : null;
+  const webhook = normalizeWebhook({
+    ...existing,
+    ...input,
+    id: existing?.id ?? input.id,
+    secret: input.secret === undefined ? existing?.secret : input.secret,
+    createdAt: existing?.createdAt,
+    updatedAt: nowIso(),
+  });
+  if (!webhook) throw new Error('Invalid webhook payload.');
+  const next = store.webhooks.filter((candidate) => candidate.id !== webhook.id);
+  next.push(webhook);
+  writeStore({ ...store, webhooks: next });
+  return publicWebhook(webhook);
+}
+
+export function deleteWebhook(webhookId) {
+  const store = readStore();
+  const next = store.webhooks.filter((webhook) => webhook.id !== webhookId);
+  if (next.length === store.webhooks.length) return false;
+  writeStore({ ...store, webhooks: next });
+  return true;
+}
+
+function signPayload(secret, body) {
+  return crypto.createHmac('sha256', secret).update(body).digest('hex');
+}
+
+function deliveryPayload(event) {
+  return {
+    id: crypto.randomUUID(),
+    protocol: 'pixcode.webhook.v1',
+    emittedAt: nowIso(),
+    event,
+  };
+}
+
+async function deliverToWebhook(webhook, event) {
+  const payload = deliveryPayload(event);
+  const body = JSON.stringify(payload);
+  const signature = signPayload(webhook.secret, body);
+  let lastError = null;
+
+  for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt += 1) {
+    try {
+      const response = await fetch(webhook.url, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-Pixcode-Event': event.type,
+          'X-Pixcode-Delivery': payload.id,
+          'X-Pixcode-Signature-256': `sha256=${signature}`,
+        },
+        body,
+      });
+      const result = {
+        ok: response.ok,
+        status: response.status,
+        attempt,
+        eventType: event.type,
+        deliveredAt: nowIso(),
+      };
+      return result;
+    } catch (error) {
+      lastError = {
+        ok: false,
+        attempt,
+        eventType: event.type,
+        deliveredAt: nowIso(),
+        error: error?.message || String(error),
+      };
+    }
+  }
+
+  return lastError;
+}
+
+function recordDelivery(webhookId, delivery) {
+  const store = readStore();
+  const next = store.webhooks.map((webhook) => (
+    webhook.id === webhookId ? { ...webhook, lastDelivery: delivery, updatedAt: nowIso() } : webhook
+  ));
+  writeStore({ ...store, webhooks: next });
+}
+
+export async function deliverWebhookEvent(event) {
+  const normalized = {
+    type: event?.type,
+    payload: event?.payload && typeof event.payload === 'object' ? event.payload : {},
+  };
+  if (!PIXCODE_WEBHOOK_EVENT_TYPES.includes(normalized.type)) {
+    return { delivered: 0, skipped: true, reason: 'unsupported_event' };
+  }
+
+  const webhooks = readStore().webhooks.filter((webhook) =>
+    webhook.enabled && webhook.events.includes(normalized.type)
+  );
+  const deliveries = [];
+  for (const webhook of webhooks) {
+    const delivery = await deliverToWebhook(webhook, normalized);
+    recordDelivery(webhook.id, delivery);
+    deliveries.push({ webhookId: webhook.id, ...delivery });
+  }
+  return { delivered: deliveries.length, deliveries };
+}
+
+export function dispatchWebhookEvent(event) {
+  deliverWebhookEvent(event).catch((error) => {
+    console.warn('[webhooks] delivery failed:', error?.message || error);
+  });
+}