@realtimex/sdk 2.0.30 → 2.0.32

package/README.md

@@ -19,5 +19,60 @@ const workspaces = await client.request("listWorkspaces");
 `REALTIMEX_BASE_URL`. Desktop and `dev:all` runtimes propagate the resolved
 dynamic `/cli` endpoint; the SDK does not guess a localhost port.
 
+## Webhook endpoint management
+
+Webhook endpoints can be managed through the generated authenticated client.
+These control-plane operations require an authenticated, user-bound session
+credential.
+
+```js
+const { createRealtimeXClient } = require("@realtimex/sdk");
+
+const client = createRealtimeXClient({
+  baseUrl: process.env.REALTIMEX_BASE_URL,
+  token: process.env.REALTIMEX_AUTH_TOKEN,
+});
+
+const created = await client.createWebhookEndpoint({
+  name: "Build tasks",
+  workspaceId: 7,
+  secret: process.env.REALTIMEX_WEBHOOK_SECRET,
+  dispatchMode: "trigger_agent",
+});
+
+await client.listWebhookDeliveries({
+  endpointId: created.endpoint.id,
+  limit: 25,
+});
+```
+
+The `secret` field is write-only. Endpoint responses report
+`secretConfigured`; they never contain the plaintext secret, ciphertext, or a
+secret-storage reference. Deletion additionally requires
+`{ confirmDestructive: true }`.
+
+## Public webhook task delivery
+
+Use a separate webhook client to trigger an existing public webhook endpoint.
+
+```js
+const { createRealtimeXWebhookClient } = require("@realtimex/sdk");
+
+const webhook = createRealtimeXWebhookClient({
+  endpointUrl: process.env.REALTIMEX_WEBHOOK_URL,
+  secret: process.env.REALTIMEX_WEBHOOK_SECRET,
+});
+
+const receipt = await webhook.trigger(
+  { prompt: "Review this task", context: { sourceId: "task-123" } },
+  { deliveryId: "task-123" }
+);
+```
+
+The client signs the exact UTF-8 request bytes with HMAC-SHA256. Network and
+server-error retries reuse the serialized body, timestamp, and delivery ID so
+the receiving endpoint can deduplicate delivery safely. A successful receipt
+confirms acceptance and routing, not agent-task completion.
+
 The package also publishes generated skill assets under
 `skills/realtimex-moderator-sdk`.

package/index.d.ts

@@ -169,6 +169,41 @@ export interface CreateThreadOptions extends RealtimeXRequestOptions {
   body?: CreateThreadBody;
 }
 
+export type CreateWebhookEndpointParams = Record<string, never>;
+export type CreateWebhookEndpointQuery = Record<string, never>;
+export type CreateWebhookEndpointHeaders = Record<string, never>;
+export type CreateWebhookEndpointBody = {
+  name: string;
+  workspaceId: number;
+  preset?: string;
+  enabled?: boolean;
+  secret: string;
+  signatureHeader?: string;
+  signaturePrefix?: string;
+  timestampHeader?: string;
+  deliveryIdHeader?: string;
+  eventTypeHeader?: string;
+  sourceHeader?: string;
+  allowedSourcePaths?: Array<string>;
+  replayWindowSeconds?: number;
+  payloadSizeLimitBytes?: number;
+  dispatchMode?: "record_only" | "send_to_thread" | "trigger_agent" | "trigger_flow";
+  triggerFlowId?: string;
+  agentTask?: Record<string, unknown>;
+  persistPayloadMode?: "none" | "attachment";
+  payloadStorageWorkspaceId?: number;
+  payloadStorageSubpath?: string;
+  dispatchInstruction?: string;
+  includePayloadPreview?: boolean;
+};
+export type CreateWebhookEndpointResponse = Record<string, unknown>;
+export interface CreateWebhookEndpointOptions extends RealtimeXRequestOptions {
+  params?: CreateWebhookEndpointParams;
+  query?: CreateWebhookEndpointQuery;
+  headers?: CreateWebhookEndpointHeaders & Record<string, string>;
+  body?: CreateWebhookEndpointBody;
+}
+
 export type CreateWorkspaceParams = Record<string, never>;
 export type CreateWorkspaceQuery = Record<string, never>;
 export type CreateWorkspaceHeaders = {
@@ -255,6 +290,22 @@ export interface DeleteThreadOptions extends RealtimeXRequestOptions {
   body?: DeleteThreadBody;
 }
 
+export type DeleteWebhookEndpointParams = {
+  endpointId: string;
+};
+export type DeleteWebhookEndpointQuery = Record<string, never>;
+export type DeleteWebhookEndpointHeaders = Record<string, never>;
+export type DeleteWebhookEndpointBody = {
+  confirmDestructive: true;
+};
+export type DeleteWebhookEndpointResponse = Record<string, unknown>;
+export interface DeleteWebhookEndpointOptions extends RealtimeXRequestOptions {
+  params?: DeleteWebhookEndpointParams;
+  query?: DeleteWebhookEndpointQuery;
+  headers?: DeleteWebhookEndpointHeaders & Record<string, string>;
+  body?: DeleteWebhookEndpointBody;
+}
+
 export type DeleteWorkspaceParams = {
   workspaceSlug: string;
 };
@@ -407,6 +458,20 @@ export interface GetThreadOptions extends RealtimeXRequestOptions {
   body?: GetThreadBody;
 }
 
+export type GetWebhookEndpointParams = {
+  endpointId: string;
+};
+export type GetWebhookEndpointQuery = Record<string, never>;
+export type GetWebhookEndpointHeaders = Record<string, never>;
+export type GetWebhookEndpointBody = unknown;
+export type GetWebhookEndpointResponse = Record<string, unknown>;
+export interface GetWebhookEndpointOptions extends RealtimeXRequestOptions {
+  params?: GetWebhookEndpointParams;
+  query?: GetWebhookEndpointQuery;
+  headers?: GetWebhookEndpointHeaders & Record<string, string>;
+  body?: GetWebhookEndpointBody;
+}
+
 export type GetWorkspaceParams = {
   workspaceSlug: string;
 };
@@ -423,6 +488,25 @@ export interface GetWorkspaceOptions extends RealtimeXRequestOptions {
   body?: GetWorkspaceBody;
 }
 
+export type GoalKickoffComposerParams = Record<string, never>;
+export type GoalKickoffComposerQuery = Record<string, never>;
+export type GoalKickoffComposerHeaders = Record<string, never>;
+export type GoalKickoffComposerBody = {
+  cdpUrl?: string;
+  mainAppUrl?: string;
+  artifactPath?: string;
+  screenshotDir?: string;
+  timeoutMs?: number;
+  confirmDestructive?: boolean;
+};
+export type GoalKickoffComposerResponse = Record<string, unknown>;
+export interface GoalKickoffComposerOptions extends RealtimeXRequestOptions {
+  params?: GoalKickoffComposerParams;
+  query?: GoalKickoffComposerQuery;
+  headers?: GoalKickoffComposerHeaders & Record<string, string>;
+  body?: GoalKickoffComposerBody;
+}
+
 export type InstallPluginParams = Record<string, never>;
 export type InstallPluginQuery = Record<string, never>;
 export type InstallPluginHeaders = {
@@ -591,6 +675,34 @@ export interface ListThreadsOptions extends RealtimeXRequestOptions {
   body?: ListThreadsBody;
 }
 
+export type ListWebhookDeliveriesParams = Record<string, never>;
+export type ListWebhookDeliveriesQuery = {
+  endpointId?: string;
+  limit?: number;
+  offset?: number;
+};
+export type ListWebhookDeliveriesHeaders = Record<string, never>;
+export type ListWebhookDeliveriesBody = unknown;
+export type ListWebhookDeliveriesResponse = Record<string, unknown>;
+export interface ListWebhookDeliveriesOptions extends RealtimeXRequestOptions {
+  params?: ListWebhookDeliveriesParams;
+  query?: ListWebhookDeliveriesQuery;
+  headers?: ListWebhookDeliveriesHeaders & Record<string, string>;
+  body?: ListWebhookDeliveriesBody;
+}
+
+export type ListWebhookEndpointsParams = Record<string, never>;
+export type ListWebhookEndpointsQuery = Record<string, never>;
+export type ListWebhookEndpointsHeaders = Record<string, never>;
+export type ListWebhookEndpointsBody = unknown;
+export type ListWebhookEndpointsResponse = Record<string, unknown>;
+export interface ListWebhookEndpointsOptions extends RealtimeXRequestOptions {
+  params?: ListWebhookEndpointsParams;
+  query?: ListWebhookEndpointsQuery;
+  headers?: ListWebhookEndpointsHeaders & Record<string, string>;
+  body?: ListWebhookEndpointsBody;
+}
+
 export type ListWorkspaceAgentSkillsParams = {
   workspaceSlug: string;
 };
@@ -826,7 +938,7 @@ export type RespondTerminalIdlePromptHeaders = {
   "x-app-id"?: string;
 };
 export type RespondTerminalIdlePromptBody = {
-  responseAction: "confirm-selected-option" | "cancel-prompt";
+  responseAction: "confirm-selected-option" | "confirm-persistent-workspace-trust" | "cancel-prompt";
   expectedEventSeq: number;
   dispatchKey: string;
 };
@@ -1359,6 +1471,22 @@ export interface TerminateTerminalSessionOptions extends RealtimeXRequestOptions
   body?: TerminateTerminalSessionBody;
 }
 
+export type TestWebhookEndpointParams = {
+  endpointId: string;
+};
+export type TestWebhookEndpointQuery = Record<string, never>;
+export type TestWebhookEndpointHeaders = Record<string, never>;
+export type TestWebhookEndpointBody = {
+  payload?: Record<string, unknown>;
+};
+export type TestWebhookEndpointResponse = Record<string, unknown>;
+export interface TestWebhookEndpointOptions extends RealtimeXRequestOptions {
+  params?: TestWebhookEndpointParams;
+  query?: TestWebhookEndpointQuery;
+  headers?: TestWebhookEndpointHeaders & Record<string, string>;
+  body?: TestWebhookEndpointBody;
+}
+
 export type TriggerWorkspaceHeartbeatParams = {
   workspaceSlug: string;
 };
@@ -1419,6 +1547,43 @@ export interface UpdateChannelOptions extends RealtimeXRequestOptions {
   body?: UpdateChannelBody;
 }
 
+export type UpdateWebhookEndpointParams = {
+  endpointId: string;
+};
+export type UpdateWebhookEndpointQuery = Record<string, never>;
+export type UpdateWebhookEndpointHeaders = Record<string, never>;
+export type UpdateWebhookEndpointBody = {
+  name?: string;
+  workspaceId?: number;
+  preset?: string;
+  enabled?: boolean;
+  secret?: string;
+  signatureHeader?: string;
+  signaturePrefix?: string;
+  timestampHeader?: string;
+  deliveryIdHeader?: string;
+  eventTypeHeader?: string;
+  sourceHeader?: string;
+  allowedSourcePaths?: Array<string>;
+  replayWindowSeconds?: number;
+  payloadSizeLimitBytes?: number;
+  dispatchMode?: "record_only" | "send_to_thread" | "trigger_agent" | "trigger_flow";
+  triggerFlowId?: string;
+  agentTask?: Record<string, unknown>;
+  persistPayloadMode?: "none" | "attachment";
+  payloadStorageWorkspaceId?: number;
+  payloadStorageSubpath?: string;
+  dispatchInstruction?: string;
+  includePayloadPreview?: boolean;
+};
+export type UpdateWebhookEndpointResponse = Record<string, unknown>;
+export interface UpdateWebhookEndpointOptions extends RealtimeXRequestOptions {
+  params?: UpdateWebhookEndpointParams;
+  query?: UpdateWebhookEndpointQuery;
+  headers?: UpdateWebhookEndpointHeaders & Record<string, string>;
+  body?: UpdateWebhookEndpointBody;
+}
+
 export type WorkspaceShellLayoutParams = Record<string, never>;
 export type WorkspaceShellLayoutQuery = Record<string, never>;
 export type WorkspaceShellLayoutHeaders = Record<string, never>;
@@ -1457,6 +1622,47 @@ export interface RealtimeXRequestOptions {
   signal?: AbortSignal;
 }
 
+export interface RealtimeXWebhookClientOptions {
+  endpointUrl?: string;
+  url?: string;
+  secret?: string;
+  signatureHeader?: string;
+  signaturePrefix?: string;
+  timestampHeader?: string;
+  deliveryIdHeader?: string;
+  eventTypeHeader?: string;
+  sourceHeader?: string;
+  eventType?: string;
+  source?: string;
+  headers?: Record<string, string>;
+  maxRetries?: number;
+  retryDelayMs?: number;
+  timeoutMs?: number;
+  fetch?: typeof fetch;
+}
+
+export interface RealtimeXWebhookTriggerOptions {
+  deliveryId?: string;
+  timestamp?: string | number;
+  eventType?: string;
+  source?: string;
+  headers?: Record<string, string>;
+  maxRetries?: number;
+  retryDelayMs?: number;
+  timeoutMs?: number;
+  signal?: AbortSignal;
+}
+
+export interface RealtimeXWebhookReceipt {
+  success: boolean;
+  accepted: boolean;
+  duplicate: boolean;
+  deliveryId: string;
+  threadId: string | number | null;
+  taskId: string | number | null;
+  [key: string]: unknown;
+}
+
 export declare class RealtimeXApiError extends Error {
   status?: number;
   statusText?: string;
@@ -1464,6 +1670,21 @@ export declare class RealtimeXApiError extends Error {
   response: Response;
 }
 
+export declare class RealtimeXWebhookError extends Error {
+  status?: number;
+  statusText?: string;
+  body: unknown;
+  response: Response | null;
+}
+
+export declare class RealtimeXWebhookClient {
+  constructor(options?: RealtimeXWebhookClientOptions);
+  trigger(
+    payload: unknown,
+    options?: RealtimeXWebhookTriggerOptions
+  ): Promise<RealtimeXWebhookReceipt>;
+}
+
 export declare class RealtimeXClient {
   constructor(options?: RealtimeXClientOptions);
   request(operationName: string, options?: RealtimeXRequestOptions): Promise<unknown>;
@@ -1488,6 +1709,9 @@ export declare class RealtimeXClient {
   /** Create a thread in one workspace. The name is optional but recommended. */
   createThread(options?: CreateThreadOptions): Promise<CreateThreadResponse>;
   createThread(workspaceSlug: string, body: CreateThreadBody, options?: Omit<CreateThreadOptions, 'params' | 'body'>): Promise<CreateThreadResponse>;
+  /** Create a webhook endpoint in an accessible workspace. secret is a write-only input. */
+  createWebhookEndpoint(options?: CreateWebhookEndpointOptions): Promise<CreateWebhookEndpointResponse>;
+  createWebhookEndpoint(body: CreateWebhookEndpointBody, options?: Omit<CreateWebhookEndpointOptions, 'body'>): Promise<CreateWebhookEndpointResponse>;
   /** Create a workspace. Requires a human-readable workspace name. */
   createWorkspace(options?: CreateWorkspaceOptions): Promise<CreateWorkspaceResponse>;
   createWorkspace(body: CreateWorkspaceBody, options?: Omit<CreateWorkspaceOptions, 'body'>): Promise<CreateWorkspaceResponse>;
@@ -1503,6 +1727,9 @@ export declare class RealtimeXClient {
   /** Delete one thread by exact workspace slug and exact thread slug. */
   deleteThread(options?: DeleteThreadOptions): Promise<DeleteThreadResponse>;
   deleteThread(params: DeleteThreadParams, options?: Omit<DeleteThreadOptions, 'params'>): Promise<DeleteThreadResponse>;
+  /** Permanently delete a visible webhook endpoint. confirmDestructive must be true. */
+  deleteWebhookEndpoint(options?: DeleteWebhookEndpointOptions): Promise<DeleteWebhookEndpointResponse>;
+  deleteWebhookEndpoint(endpointId: string, body: DeleteWebhookEndpointBody, options?: Omit<DeleteWebhookEndpointOptions, 'params' | 'body'>): Promise<DeleteWebhookEndpointResponse>;
   /** Delete one workspace by exact workspace slug. */
   deleteWorkspace(options?: DeleteWorkspaceOptions): Promise<DeleteWorkspaceResponse>;
   deleteWorkspace(workspaceSlug: string, options?: Omit<DeleteWorkspaceOptions, 'params'>): Promise<DeleteWorkspaceResponse>;
@@ -1530,9 +1757,15 @@ export declare class RealtimeXClient {
   /** Get one thread by exact workspace slug and exact thread slug. */
   getThread(options?: GetThreadOptions): Promise<GetThreadResponse>;
   getThread(params: GetThreadParams, options?: Omit<GetThreadOptions, 'params'>): Promise<GetThreadResponse>;
+  /** Get one visible webhook endpoint by endpoint id. The response reports secretConfigured but never returns the secret. */
+  getWebhookEndpoint(options?: GetWebhookEndpointOptions): Promise<GetWebhookEndpointResponse>;
+  getWebhookEndpoint(endpointId: string, options?: Omit<GetWebhookEndpointOptions, 'params'>): Promise<GetWebhookEndpointResponse>;
   /** Get one workspace by exact workspace slug. */
   getWorkspace(options?: GetWorkspaceOptions): Promise<GetWorkspaceResponse>;
   getWorkspace(workspaceSlug: string, options?: Omit<GetWorkspaceOptions, 'params'>): Promise<GetWorkspaceResponse>;
+  /** Verify the shared Project/global Goal kickoff composer, routing, attachment authorization, retry, preview, and responsive layouts. */
+  goalKickoffComposer(options?: GoalKickoffComposerOptions): Promise<GoalKickoffComposerResponse>;
+  goalKickoffComposer(body: GoalKickoffComposerBody, options?: Omit<GoalKickoffComposerOptions, 'body'>): Promise<GoalKickoffComposerResponse>;
   /** Install a plugin from a local source directory on the same machine as the server. Pass an absolute path containing realtimex.plugin.json. Pass force=true to replace an already-installed version; its saved configuration (including secrets) is preserved. */
   installPlugin(options?: InstallPluginOptions): Promise<InstallPluginResponse>;
   installPlugin(body: InstallPluginBody, options?: Omit<InstallPluginOptions, 'body'>): Promise<InstallPluginResponse>;
@@ -1560,6 +1793,11 @@ export declare class RealtimeXClient {
   /** List threads for one exact workspace slug. */
   listThreads(options?: ListThreadsOptions): Promise<ListThreadsResponse>;
   listThreads(workspaceSlug: string, options?: Omit<ListThreadsOptions, 'params'>): Promise<ListThreadsResponse>;
+  /** List bounded delivery metadata for visible webhook endpoints. Raw headers, bodies, signatures, and payload fields are omitted. */
+  listWebhookDeliveries(options?: ListWebhookDeliveriesOptions): Promise<ListWebhookDeliveriesResponse>;
+  listWebhookDeliveries(query?: ListWebhookDeliveriesQuery, options?: Omit<ListWebhookDeliveriesOptions, 'query'>): Promise<ListWebhookDeliveriesResponse>;
+  /** List webhook endpoints visible to the authenticated user. Secrets are never returned. */
+  listWebhookEndpoints(options?: ListWebhookEndpointsOptions): Promise<ListWebhookEndpointsResponse>;
   /** List published agent skills with enabled/disabled state for one exact workspace slug. */
   listWorkspaceAgentSkills(options?: ListWorkspaceAgentSkillsOptions): Promise<ListWorkspaceAgentSkillsResponse>;
   listWorkspaceAgentSkills(workspaceSlug: string, options?: Omit<ListWorkspaceAgentSkillsOptions, 'params'>): Promise<ListWorkspaceAgentSkillsResponse>;
@@ -1672,6 +1910,9 @@ export declare class RealtimeXClient {
   /** Terminate a terminal runtime session by detaching any controller and closing the underlying PTY session. */
   terminateTerminalSession(options?: TerminateTerminalSessionOptions): Promise<TerminateTerminalSessionResponse>;
   terminateTerminalSession(sessionId: string, options?: Omit<TerminateTerminalSessionOptions, 'params'>): Promise<TerminateTerminalSessionResponse>;
+  /** Submit an optional JSON payload as a signed test delivery through a visible webhook endpoint. */
+  testWebhookEndpoint(options?: TestWebhookEndpointOptions): Promise<TestWebhookEndpointResponse>;
+  testWebhookEndpoint(endpointId: string, body: TestWebhookEndpointBody, options?: Omit<TestWebhookEndpointOptions, 'params' | 'body'>): Promise<TestWebhookEndpointResponse>;
   /** Trigger the default HEARTBEAT.md task for a workspace immediately. Falls back to the legacy heartbeat executor when no tasks are defined. */
   triggerWorkspaceHeartbeat(options?: TriggerWorkspaceHeartbeatOptions): Promise<TriggerWorkspaceHeartbeatResponse>;
   triggerWorkspaceHeartbeat(workspaceSlug: string, body: TriggerWorkspaceHeartbeatBody, options?: Omit<TriggerWorkspaceHeartbeatOptions, 'params' | 'body'>): Promise<TriggerWorkspaceHeartbeatResponse>;
@@ -1681,6 +1922,9 @@ export declare class RealtimeXClient {
   /** Update one chat channel by exact channel id. Only channel writable fields are changed. */
   updateChannel(options?: UpdateChannelOptions): Promise<UpdateChannelResponse>;
   updateChannel(channelId: string, body: UpdateChannelBody, options?: Omit<UpdateChannelOptions, 'params' | 'body'>): Promise<UpdateChannelResponse>;
+  /** Update a visible webhook endpoint. Passing secret rotates it; the value is never returned. */
+  updateWebhookEndpoint(options?: UpdateWebhookEndpointOptions): Promise<UpdateWebhookEndpointResponse>;
+  updateWebhookEndpoint(endpointId: string, body: UpdateWebhookEndpointBody, options?: Omit<UpdateWebhookEndpointOptions, 'params' | 'body'>): Promise<UpdateWebhookEndpointResponse>;
   /** Verify workspace navigation, title-bar containment, Files dock behavior, and action contrast at desktop and compact viewports. */
   workspaceShellLayout(options?: WorkspaceShellLayoutOptions): Promise<WorkspaceShellLayoutResponse>;
   workspaceShellLayout(body: WorkspaceShellLayoutBody, options?: Omit<WorkspaceShellLayoutOptions, 'body'>): Promise<WorkspaceShellLayoutResponse>;
@@ -1689,6 +1933,9 @@ export declare class RealtimeXClient {
 export declare function createRealtimeXClient(
   options?: RealtimeXClientOptions
 ): RealtimeXClient;
+export declare function createRealtimeXWebhookClient(
+  options?: RealtimeXWebhookClientOptions
+): RealtimeXWebhookClient;
 export declare const createClient: typeof createRealtimeXClient;
 export declare const operations: Record<
   string,

package/index.js

@@ -1,5 +1,7 @@
 'use strict';
 
+const crypto = require('node:crypto');
+
 const operations = {
   "approveChannelPairingCode": {
     "method": "POST",
@@ -80,6 +82,14 @@ const operations = {
     ],
     "hasBody": true
   },
+  "createWebhookEndpoint": {
+    "method": "POST",
+    "path": "/create-webhook-endpoint",
+    "pathParams": [],
+    "queryParams": [],
+    "headerParams": [],
+    "hasBody": true
+  },
   "createWorkspace": {
     "method": "POST",
     "path": "/create-workspace",
@@ -140,6 +150,16 @@ const operations = {
     ],
     "hasBody": false
   },
+  "deleteWebhookEndpoint": {
+    "method": "DELETE",
+    "path": "/delete-webhook-endpoint/{endpointId}",
+    "pathParams": [
+      "endpointId"
+    ],
+    "queryParams": [],
+    "headerParams": [],
+    "hasBody": true
+  },
   "deleteWorkspace": {
     "method": "DELETE",
     "path": "/delete-workspace/{workspaceSlug}",
@@ -256,6 +276,16 @@ const operations = {
     ],
     "hasBody": false
   },
+  "getWebhookEndpoint": {
+    "method": "GET",
+    "path": "/get-webhook-endpoint/{endpointId}",
+    "pathParams": [
+      "endpointId"
+    ],
+    "queryParams": [],
+    "headerParams": [],
+    "hasBody": false
+  },
   "getWorkspace": {
     "method": "GET",
     "path": "/get-workspace/{workspaceSlug}",
@@ -268,6 +298,14 @@ const operations = {
     ],
     "hasBody": false
   },
+  "goalKickoffComposer": {
+    "method": "POST",
+    "path": "/goal-kickoff-composer",
+    "pathParams": [],
+    "queryParams": [],
+    "headerParams": [],
+    "hasBody": true
+  },
   "installPlugin": {
     "method": "POST",
     "path": "/install-plugin",
@@ -389,6 +427,26 @@ const operations = {
     ],
     "hasBody": false
   },
+  "listWebhookDeliveries": {
+    "method": "GET",
+    "path": "/list-webhook-deliveries",
+    "pathParams": [],
+    "queryParams": [
+      "endpointId",
+      "limit",
+      "offset"
+    ],
+    "headerParams": [],
+    "hasBody": false
+  },
+  "listWebhookEndpoints": {
+    "method": "GET",
+    "path": "/list-webhook-endpoints",
+    "pathParams": [],
+    "queryParams": [],
+    "headerParams": [],
+    "hasBody": false
+  },
   "listWorkspaceAgentSkills": {
     "method": "GET",
     "path": "/list-workspace-agent-skills/{workspaceSlug}",
@@ -819,6 +877,16 @@ const operations = {
     ],
     "hasBody": false
   },
+  "testWebhookEndpoint": {
+    "method": "POST",
+    "path": "/test-webhook-endpoint/{endpointId}",
+    "pathParams": [
+      "endpointId"
+    ],
+    "queryParams": [],
+    "headerParams": [],
+    "hasBody": true
+  },
   "triggerWorkspaceHeartbeat": {
     "method": "POST",
     "path": "/trigger-workspace-heartbeat/{workspaceSlug}",
@@ -855,6 +923,16 @@ const operations = {
     ],
     "hasBody": true
   },
+  "updateWebhookEndpoint": {
+    "method": "POST",
+    "path": "/update-webhook-endpoint/{endpointId}",
+    "pathParams": [
+      "endpointId"
+    ],
+    "queryParams": [],
+    "headerParams": [],
+    "hasBody": true
+  },
   "workspaceShellLayout": {
     "method": "POST",
     "path": "/workspace-shell-layout",
@@ -876,6 +954,17 @@ class RealtimeXApiError extends Error {
   }
 }
 
+class RealtimeXWebhookError extends Error {
+  constructor(message, response = null, body = null, cause = null) {
+    super(message, cause ? { cause } : undefined);
+    this.name = 'RealtimeXWebhookError';
+    this.status = response && response.status;
+    this.statusText = response && response.statusText;
+    this.body = body;
+    this.response = response;
+  }
+}
+
 function joinUrl(baseUrl, pathname) {
   const base = String(baseUrl || '').replace(/\/+$/g, '');
   const path = String(pathname || '').replace(/^\/+/, '');
@@ -929,6 +1018,220 @@ async function parseResponseBody(response) {
   }
 }
 
+function normalizeWebhookEndpointUrl(value) {
+  const normalized = String(value || '').trim();
+  if (!normalized) {
+    throw new Error(
+      'RealtimeX webhook URL is unavailable; pass { endpointUrl } or set REALTIMEX_WEBHOOK_URL.'
+    );
+  }
+  const parsed = new URL(normalized);
+  if (!['http:', 'https:'].includes(parsed.protocol)) {
+    throw new Error('RealtimeX webhook URL must use http or https.');
+  }
+  if (parsed.username || parsed.password) {
+    throw new Error('RealtimeX webhook URL must not contain embedded credentials.');
+  }
+  return parsed.toString();
+}
+
+function normalizeRetryCount(value, fallback = 2) {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 0 || parsed > 10) return fallback;
+  return parsed;
+}
+
+function normalizeTimeout(value, fallback = 15000) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0) return fallback;
+  return Math.min(Math.floor(parsed), 120000);
+}
+
+function waitForRetry(delayMs, signal) {
+  const delay = Math.max(0, Number(delayMs) || 0);
+  if (delay === 0) return Promise.resolve();
+  return new Promise((resolve, reject) => {
+    const finish = () => {
+      if (signal) signal.removeEventListener('abort', abort);
+      resolve();
+    };
+    const timeout = setTimeout(finish, delay);
+    const abort = () => {
+      clearTimeout(timeout);
+      signal.removeEventListener('abort', abort);
+      reject(signal.reason || new Error('Webhook request aborted.'));
+    };
+    if (signal) {
+      if (signal.aborted) return abort();
+      signal.addEventListener('abort', abort, { once: true });
+    }
+  });
+}
+
+function createAttemptSignal(externalSignal, timeoutMs) {
+  const controller = new AbortController();
+  const abortFromExternal = () => {
+    controller.abort(externalSignal.reason || new Error('Webhook request aborted.'));
+  };
+  if (externalSignal) {
+    if (externalSignal.aborted) abortFromExternal();
+    else externalSignal.addEventListener('abort', abortFromExternal, { once: true });
+  }
+  const timeout = setTimeout(
+    () => controller.abort(new Error('Webhook request timed out.')),
+    timeoutMs
+  );
+  return {
+    signal: controller.signal,
+    cleanup() {
+      clearTimeout(timeout);
+      if (externalSignal) {
+        externalSignal.removeEventListener('abort', abortFromExternal);
+      }
+    },
+  };
+}
+
+class RealtimeXWebhookClient {
+  constructor(options = {}) {
+    const env = typeof process !== 'undefined' ? process.env || {} : {};
+    this.endpointUrl = normalizeWebhookEndpointUrl(
+      options.endpointUrl || options.url || env.REALTIMEX_WEBHOOK_URL
+    );
+    this.secret = String(options.secret || env.REALTIMEX_WEBHOOK_SECRET || '');
+    if (!this.secret) {
+      throw new Error(
+        'RealtimeX webhook secret is unavailable; pass { secret } or set REALTIMEX_WEBHOOK_SECRET.'
+      );
+    }
+    this.fetch = options.fetch || globalThis.fetch;
+    if (typeof this.fetch !== 'function') {
+      throw new Error('A fetch implementation is required. Use Node 18+ or pass { fetch }.');
+    }
+    this.signatureHeader =
+      options.signatureHeader ||
+      env.REALTIMEX_WEBHOOK_SIGNATURE_HEADER ||
+      'X-Webhook-Signature-256';
+    this.signaturePrefix =
+      options.signaturePrefix ?? env.REALTIMEX_WEBHOOK_SIGNATURE_PREFIX ?? 'sha256=';
+    this.timestampHeader =
+      options.timestampHeader ||
+      env.REALTIMEX_WEBHOOK_TIMESTAMP_HEADER ||
+      'X-Webhook-Timestamp';
+    this.deliveryIdHeader =
+      options.deliveryIdHeader ||
+      env.REALTIMEX_WEBHOOK_DELIVERY_ID_HEADER ||
+      'X-Webhook-Id';
+    this.eventTypeHeader =
+      options.eventTypeHeader ||
+      env.REALTIMEX_WEBHOOK_EVENT_TYPE_HEADER ||
+      'X-Webhook-Event';
+    this.sourceHeader =
+      options.sourceHeader ||
+      env.REALTIMEX_WEBHOOK_SOURCE_HEADER ||
+      'X-Webhook-Source';
+    this.defaultEventType =
+      options.eventType || env.REALTIMEX_WEBHOOK_EVENT_TYPE || 'realtimex.task';
+    this.defaultSource =
+      options.source || env.REALTIMEX_WEBHOOK_SOURCE || 'local-app';
+    this.defaultHeaders = { ...(options.headers || {}) };
+    this.maxRetries = normalizeRetryCount(options.maxRetries, 2);
+    const configuredRetryDelay = Number(options.retryDelayMs);
+    this.retryDelayMs = Number.isFinite(configuredRetryDelay) && configuredRetryDelay >= 0
+      ? configuredRetryDelay
+      : 250;
+    this.timeoutMs = normalizeTimeout(options.timeoutMs, 15000);
+  }
+
+  async trigger(payload, options = {}) {
+    if (payload === undefined) {
+      throw new Error('RealtimeX webhook payload is required.');
+    }
+    const serialized = typeof payload === 'string' ? payload : JSON.stringify(payload);
+    if (serialized === undefined) {
+      throw new Error('RealtimeX webhook payload is not JSON serializable.');
+    }
+    const body = Buffer.from(serialized, 'utf8');
+    const deliveryId = String(options.deliveryId || crypto.randomUUID());
+    const timestamp = String(
+      options.timestamp || Math.floor(Date.now() / 1000)
+    );
+    const signature = crypto
+      .createHmac('sha256', this.secret)
+      .update(body)
+      .digest('hex');
+    const headers = {
+      ...this.defaultHeaders,
+      ...(options.headers || {}),
+      'content-type': 'application/json',
+      [this.signatureHeader]: String(this.signaturePrefix || '') + signature,
+      [this.timestampHeader]: timestamp,
+      [this.deliveryIdHeader]: deliveryId,
+      [this.eventTypeHeader]: String(options.eventType || this.defaultEventType),
+      [this.sourceHeader]: String(options.source || this.defaultSource),
+    };
+    const maxRetries = normalizeRetryCount(options.maxRetries, this.maxRetries);
+    const retryDelayMs =
+      options.retryDelayMs === undefined
+        ? this.retryDelayMs
+        : Math.max(0, Number(options.retryDelayMs) || 0);
+    const timeoutMs = normalizeTimeout(options.timeoutMs, this.timeoutMs);
+
+    for (let attempt = 0; attempt <= maxRetries; attempt += 1) {
+      const attemptSignal = createAttemptSignal(options.signal, timeoutMs);
+      try {
+        const response = await this.fetch(this.endpointUrl, {
+          method: 'POST',
+          headers,
+          body,
+          signal: attemptSignal.signal,
+        });
+        const responseBody = await parseResponseBody(response);
+        if (response.status >= 500 && attempt < maxRetries) {
+          await waitForRetry(retryDelayMs * (attempt + 1), options.signal);
+          continue;
+        }
+        if (!response.ok) {
+          throw new RealtimeXWebhookError(
+            'RealtimeX webhook request failed: ' +
+              response.status +
+              ' ' +
+              response.statusText,
+            response,
+            responseBody
+          );
+        }
+        return responseBody;
+      } catch (error) {
+        if (error instanceof RealtimeXWebhookError) throw error;
+        if (options.signal && options.signal.aborted) {
+          throw new RealtimeXWebhookError(
+            'RealtimeX webhook request aborted.',
+            null,
+            null,
+            error
+          );
+        }
+        if (attempt >= maxRetries) {
+          const timedOut = attemptSignal.signal.aborted;
+          throw new RealtimeXWebhookError(
+            timedOut
+              ? 'RealtimeX webhook request timed out.'
+              : 'RealtimeX webhook request failed: ' + (error.message || String(error)),
+            null,
+            null,
+            error
+          );
+        }
+        await waitForRetry(retryDelayMs * (attempt + 1), options.signal);
+      } finally {
+        attemptSignal.cleanup();
+      }
+    }
+    throw new RealtimeXWebhookError('RealtimeX webhook request failed.');
+  }
+}
+
 function isPlainObject(value) {
   return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
 }
@@ -1112,6 +1415,13 @@ class RealtimeXClient {
     );
   }
 
+  createWebhookEndpoint(...args) {
+    return this.request(
+      "createWebhookEndpoint",
+      normalizeOperationOptions(operations["createWebhookEndpoint"], args)
+    );
+  }
+
   createWorkspace(...args) {
     return this.request(
       "createWorkspace",
@@ -1147,6 +1457,13 @@ class RealtimeXClient {
     );
   }
 
+  deleteWebhookEndpoint(...args) {
+    return this.request(
+      "deleteWebhookEndpoint",
+      normalizeOperationOptions(operations["deleteWebhookEndpoint"], args)
+    );
+  }
+
   deleteWorkspace(...args) {
     return this.request(
       "deleteWorkspace",
@@ -1210,6 +1527,13 @@ class RealtimeXClient {
     );
   }
 
+  getWebhookEndpoint(...args) {
+    return this.request(
+      "getWebhookEndpoint",
+      normalizeOperationOptions(operations["getWebhookEndpoint"], args)
+    );
+  }
+
   getWorkspace(...args) {
     return this.request(
       "getWorkspace",
@@ -1217,6 +1541,13 @@ class RealtimeXClient {
     );
   }
 
+  goalKickoffComposer(...args) {
+    return this.request(
+      "goalKickoffComposer",
+      normalizeOperationOptions(operations["goalKickoffComposer"], args)
+    );
+  }
+
   installPlugin(...args) {
     return this.request(
       "installPlugin",
@@ -1294,6 +1625,20 @@ class RealtimeXClient {
     );
   }
 
+  listWebhookDeliveries(...args) {
+    return this.request(
+      "listWebhookDeliveries",
+      normalizeOperationOptions(operations["listWebhookDeliveries"], args)
+    );
+  }
+
+  listWebhookEndpoints(...args) {
+    return this.request(
+      "listWebhookEndpoints",
+      normalizeOperationOptions(operations["listWebhookEndpoints"], args)
+    );
+  }
+
   listWorkspaceAgentSkills(...args) {
     return this.request(
       "listWorkspaceAgentSkills",
@@ -1560,6 +1905,13 @@ class RealtimeXClient {
     );
   }
 
+  testWebhookEndpoint(...args) {
+    return this.request(
+      "testWebhookEndpoint",
+      normalizeOperationOptions(operations["testWebhookEndpoint"], args)
+    );
+  }
+
   triggerWorkspaceHeartbeat(...args) {
     return this.request(
       "triggerWorkspaceHeartbeat",
@@ -1581,6 +1933,13 @@ class RealtimeXClient {
     );
   }
 
+  updateWebhookEndpoint(...args) {
+    return this.request(
+      "updateWebhookEndpoint",
+      normalizeOperationOptions(operations["updateWebhookEndpoint"], args)
+    );
+  }
+
   workspaceShellLayout(...args) {
     return this.request(
       "workspaceShellLayout",
@@ -1593,11 +1952,18 @@ function createRealtimeXClient(options = {}) {
   return new RealtimeXClient(options);
 }
 
+function createRealtimeXWebhookClient(options = {}) {
+  return new RealtimeXWebhookClient(options);
+}
+
 module.exports = {
   RealtimeXApiError,
   RealtimeXClient,
+  RealtimeXWebhookClient,
+  RealtimeXWebhookError,
   createClient: createRealtimeXClient,
   createRealtimeXClient,
+  createRealtimeXWebhookClient,
   operations,
-  version: "2.0.30",
+  version: "2.0.32",
 };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@realtimex/sdk",
-    "version": "2.0.30",
+    "version": "2.0.32",
     "description": "RealtimeX runtime SDK package and moderator agent skill assets.",
     "private": false,
     "main": "./index.js",

package/skills/realtimex-moderator-sdk/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: realtimex-moderator-sdk
-description: "Use the RealTimeX API through the generated CLI for workspace, thread, terminal-agent sessions, channel (Telegram, Zalo, Discord), skills, plugins and send messages, setup personality, heartbeat tasks operations, publish and manage artifacts, run tour guide to setup working dir."
+description: "Use the RealTimeX API through the generated CLI for workspace, thread, terminal-agent sessions, channel (Telegram, Zalo, Discord), skills, plugins, webhook endpoint management and delivery inspection, send messages, setup personality, heartbeat tasks operations, publish and manage artifacts, run tour guide to setup working dir."
 author: ""
 license: "Apache-2.0"
 argument-hint: "<command> [args] | install cli"
@@ -20,15 +20,15 @@ This skill drives the `realtimex-pp-cli` binary. Verify the CLI is installed and
 
 1. Install or reinstall the pinned version via npm:
    ```bash
-   npm install -g @realtimex/pp-cli@2.0.30
+   npm install -g @realtimex/pp-cli@2.0.32
    ```
 2. Verify the exact version:
    ```bash
    realtimex-pp-cli --version
    ```
-   The output must be `realtimex-pp-cli 2.0.30`.
+   The output must be `realtimex-pp-cli 2.0.32`.
 
-If `--version` reports "command not found" after install, the npm global bin directory is not on `$PATH`. If it reports any version other than `2.0.30`, reinstall with the pinned npm command above. Do not proceed with skill commands until exact-version verification succeeds.
+If `--version` reports "command not found" after install, the npm global bin directory is not on `$PATH`. If it reports any version other than `2.0.32`, reinstall with the pinned npm command above. Do not proceed with skill commands until exact-version verification succeeds.
 
 * Always run first:
 
@@ -66,6 +66,10 @@ If `--version` reports "command not found" after install, the npm global bin dir
 
 - `realtimex-pp-cli create-thread <workspaceSlug>` — Create a thread in one workspace. The name is optional but recommended.
 
+**create-webhook-endpoint** — Manage create webhook endpoint
+
+- `realtimex-pp-cli create-webhook-endpoint` — Create a webhook endpoint in an accessible workspace. secret is a write-only input.
+
 **create-workspace** — Manage create workspace
 
 - `realtimex-pp-cli create-workspace` — Create a workspace. Requires a human-readable workspace name.
@@ -86,6 +90,10 @@ If `--version` reports "command not found" after install, the npm global bin dir
 
 - `realtimex-pp-cli delete-thread <workspaceSlug> <threadSlug>` — Delete one thread by exact workspace slug and exact thread slug.
 
+**delete-webhook-endpoint** — Manage delete webhook endpoint
+
+- `realtimex-pp-cli delete-webhook-endpoint <endpointId>` — Permanently delete a visible webhook endpoint. confirmDestructive must be true.
+
 **delete-workspace** — Manage delete workspace
 
 - `realtimex-pp-cli delete-workspace <workspaceSlug>` — Delete one workspace by exact workspace slug.
@@ -122,10 +130,18 @@ If `--version` reports "command not found" after install, the npm global bin dir
 
 - `realtimex-pp-cli get-thread <workspaceSlug> <threadSlug>` — Get one thread by exact workspace slug and exact thread slug.
 
+**get-webhook-endpoint** — Manage get webhook endpoint
+
+- `realtimex-pp-cli get-webhook-endpoint <endpointId>` — Get one visible webhook endpoint by endpoint id. The response reports secretConfigured but never returns the secret.
+
 **get-workspace** — Manage get workspace
 
 - `realtimex-pp-cli get-workspace <workspaceSlug>` — Get one workspace by exact workspace slug.
 
+**goal-kickoff-composer** — Manage goal kickoff composer
+
+- `realtimex-pp-cli goal-kickoff-composer` — Verify the shared Project/global Goal kickoff composer, routing, attachment authorization, retry, preview
+
 **install-plugin** — Manage install plugin
 
 - `realtimex-pp-cli install-plugin` — Install a plugin from a local source directory on the same machine as the server.
@@ -170,6 +186,14 @@ If `--version` reports "command not found" after install, the npm global bin dir
 
 - `realtimex-pp-cli list-threads <workspaceSlug>` — List threads for one exact workspace slug.
 
+**list-webhook-deliveries** — Manage list webhook deliveries
+
+- `realtimex-pp-cli list-webhook-deliveries` — List bounded delivery metadata for visible webhook endpoints.
+
+**list-webhook-endpoints** — Manage list webhook endpoints
+
+- `realtimex-pp-cli list-webhook-endpoints` — List webhook endpoints visible to the authenticated user. Secrets are never returned.
+
 **list-workspace-agent-skills** — Manage list workspace agent skills
 
 - `realtimex-pp-cli list-workspace-agent-skills <workspaceSlug>` — List published agent skills with enabled/disabled state for one exact workspace slug.
@@ -318,6 +342,10 @@ If `--version` reports "command not found" after install, the npm global bin dir
 
 - `realtimex-pp-cli terminate-terminal-session <sessionId>` — Terminate a terminal runtime session by detaching any controller and closing the underlying PTY session.
 
+**test-webhook-endpoint** — Manage test webhook endpoint
+
+- `realtimex-pp-cli test-webhook-endpoint <endpointId>` — Submit an optional JSON payload as a signed test delivery through a visible webhook endpoint.
+
 **trigger-workspace-heartbeat** — Manage trigger workspace heartbeat
 
 - `realtimex-pp-cli trigger-workspace-heartbeat <workspaceSlug>` — Trigger the default HEARTBEAT.md task for a workspace immediately.
@@ -330,6 +358,10 @@ If `--version` reports "command not found" after install, the npm global bin dir
 
 - `realtimex-pp-cli update-channel <channelId>` — Update one chat channel by exact channel id. Only channel writable fields are changed.
 
+**update-webhook-endpoint** — Manage update webhook endpoint
+
+- `realtimex-pp-cli update-webhook-endpoint <endpointId>` — Update a visible webhook endpoint. Passing secret rotates it; the value is never returned.
+
 **workspace-shell-layout** — Manage workspace shell layout
 
 - `realtimex-pp-cli workspace-shell-layout` — Verify workspace navigation, title-bar containment, Files dock behavior
@@ -460,9 +492,9 @@ Verify: `claude mcp list`
    ```bash
    realtimex-pp-cli --version
    ```
-   If the command is missing or the output is not exactly `realtimex-pp-cli 2.0.30`, reinstall the pinned version:
+   If the command is missing or the output is not exactly `realtimex-pp-cli 2.0.32`, reinstall the pinned version:
    ```bash
-   npm install -g @realtimex/pp-cli@2.0.30
+   npm install -g @realtimex/pp-cli@2.0.32
    ```
    Then run `realtimex-pp-cli --version` again and proceed only after exact-version verification succeeds.
 2. Match the user query to the best command from the Unique Capabilities and Command Reference above.
@@ -525,6 +557,13 @@ For `send-channel-file`:
 * In desktop/local runtime, the CLI should send the absolute local `filePath` to the server. The server validates the path against allowed storage/temp roots before sending through the channel. Base64 upload is fallback transport, not the preferred path.
 * The server validates the delivery context, active channel session, plugin state, runtime binding when supplied, and file size/type handling before delivery.
 
+For webhook endpoint management:
+
+* These operations require an authenticated, user-bound session credential.
+* Treat `secret` as write-only input for creation or rotation. Never expect, request, print, or persist a plaintext secret from endpoint responses.
+* Use `list-webhook-deliveries` for bounded metadata inspection. Raw request headers, signatures, bodies, and normalized payload fields are intentionally unavailable.
+* Pass `confirmDestructive=true` only after the user has explicitly requested permanent endpoint deletion.
+
 For workspace default-agent setup:
 
 * Use `prepare.agents` only.