# Webhooks ## `client.webhooks.unwrap(RequestOptionsoptions?): void` **** `` ### Example ```typescript import Cadenya from '@cadenya/cadenya'; const client = new Cadenya({ apiKey: process.env['CADENYA_API_KEY'], // This is the default and can be omitted }); await client.webhooks.unwrap(); ``` ## `client.webhooks.unsafeUnwrap(RequestOptionsoptions?): void` **** `` ### Example ```typescript import Cadenya from '@cadenya/cadenya'; const client = new Cadenya({ apiKey: process.env['CADENYA_API_KEY'], // This is the default and can be omitted }); await client.webhooks.unsafeUnwrap(); ``` ## Domain Types ### Unsafe Unwrap Webhook Event - `UnsafeUnwrapWebhookEvent` The envelope for an objective event webhook delivery. Contains timestamp, event type, and the webhook data payload. - `data: Data` The webhook data payload with flat top-level keys for agent, variation, objective, and event. - `agent: ResourceMetadata` Standard metadata for persistent, named resources (e.g., agents, tools, prompts) - `id: string` Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...") - `accountId: string` Account this resource belongs to for multi-tenant isolation (prefixed ULID) - `createdAt: string` Timestamp when this resource was created - `name: string` Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly - `profileId: string` ID of the actor (user or service account) that created this resource - `workspaceId: string` Workspace this resource belongs to for organizational grouping (prefixed ULID) - `externalId?: string` External ID for the resource (e.g., a workflow ID from an external system) - `labels?: Record` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `agentVariation: ResourceMetadata` Standard metadata for persistent, named resources (e.g., agents, tools, prompts) - `objective: OperationMetadata` Metadata for ephemeral operations and activities (e.g., objectives, executions, runs) - `id: string` Unique identifier for the operation (prefixed ULID, e.g., "obj_01HXK...") - `accountId: string` Account this operation belongs to for multi-tenant isolation (prefixed ULID) - `createdAt: string` Timestamp when this operation was created ULID includes timestamp information, but this explicit field enables easier querying - `profileId: string` ID of the actor (user or service account) that created this operation - `workspaceId: string` Workspace this operation belongs to for organizational grouping (prefixed ULID) - `externalId?: string` External ID for the operation (e.g., a workflow ID from an external system) - `labels?: Record` Arbitrary key-value pairs for categorization and filtering Examples: {"priority": "high", "source": "api", "workflow": "onboarding"} - `objectiveEvent: ObjectiveEvent` - `data: ObjectiveEventData` - `assistantMessage?: AssistantMessage` - `content?: string` - `toolCalls?: Array` - `arguments?: string` - `functionName?: string` - `tool?: CallableTool` CallableTool is a union that represents a tool that can be called by an agent. In Cadenya, a tool that is used within an agent objective might be a user-defined tool (IE: MCP, HTTP), another Agent (useful to separate context), or a Cadenya Tool (one Cadenya provides). - `agent?: ResourceMetadata` Standard metadata for persistent, named resources (e.g., agents, tools, prompts) - `cadenyaProvidedTool?: ResourceMetadata` Standard metadata for persistent, named resources (e.g., agents, tools, prompts) - `tool?: ResourceMetadata` Standard metadata for persistent, named resources (e.g., agents, tools, prompts) - `contextWindowCompacted?: ContextWindowCompacted` - `messagesCompacted?: number` Number of messages that were compacted - `newContextWindow?: ObjectiveContextWindowData` The new context window created by this compaction - `completionTokens?: number` A calculated value for how many completion tokens (output tokens) have been used in this context window - `objectiveId?: string` The objective's ID that this window belongs to - `previousWindowContinueInstructions?: string` The instructions for this window to continue from a previous window's chat history. - `promptTokens?: number` A calculated value for how many prompt tokens (input tokens) have been used in this context window - `sequence?: number` sequence is a numeric representation of which context window this is. Sequences are useful to perform a max(sequence) on in order to calculate how many context windows an objective has. - `strategies?: Array` The strategies that were applied during this compaction - `summary?: string` The summary generated by the summarization strategy, if used. - `error?: ObjectiveError` - `message?: string` - `type?: string` - `subObjectiveCreated?: SubObjectiveCreated` - `metadata?: OperationMetadata` Metadata for ephemeral operations and activities (e.g., objectives, executions, runs) - `toolApprovalRequested?: ToolApprovalRequested` - `toolCallId?: string` The ID of the objective tool call record. Use this ID with the ApproveToolCall or DenyToolCall RPCs to approve or deny the tool call. - `toolApproved?: ToolApproved` - `toolCallId?: string` The ID of the objective tool call record that was approved via the ApproveToolCall RPC. - `toolCalled?: ToolCalled` - `toolCallId?: string` The ID of the objective tool call record that was executed. - `toolDenied?: ToolDenied` - `memo?: string` The memo provided by the reviewer when denying the tool call. This is passed to the agent to provide further instructions. - `toolCallId?: string` The ID of the objective tool call record that was denied via the DenyToolCall RPC. - `toolError?: ToolError` - `message?: string` - `toolCallId?: string` The ID of the objective tool call record that encountered an error during execution. - `toolResult?: ToolResult` - `content?: string` - `toolCallId?: string` - `type?: string` - `userMessage?: UserMessage` - `content?: string` - `metadata: OperationMetadata` Metadata for ephemeral operations and activities (e.g., objectives, executions, runs) - `contextWindowId?: string` - `info?: ObjectiveEventInfo` - `createdBy?: Profile` Profile represents a human user at the account level. Profiles are account-scoped resources that can be associated with multiple workspaces through the Actor model. Authentication for profiles is handled via SSO/OAuth (WorkOS). - `metadata: AccountResourceMetadata` AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace. - `id: string` Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...") - `accountId: string` Account this resource belongs to for multi-tenant isolation (prefixed ULID) - `name: string` Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly - `profileId: string` - `externalId?: string` External ID for the resource (e.g., a workflow ID from an external system) - `labels?: Record` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `spec: ProfileSpec` ProfileSpec contains the profile-specific fields - `type: "PROFILE_TYPE_USER" | "PROFILE_TYPE_API_KEY" | "PROFILE_TYPE_SYSTEM"` Type is the type of profile. User's are humans, API keys are computers. You know the deal. - `"PROFILE_TYPE_USER"` - `"PROFILE_TYPE_API_KEY"` - `"PROFILE_TYPE_SYSTEM"` - `email?: string` Email address of the user (required, unique per account) - `name?: string` Display name for the user (e.g., "Bobby Tables") - `objective?: OperationMetadata` Metadata for ephemeral operations and activities (e.g., objectives, executions, runs) - `timestamp: string` - `type: string` The event type, prefixed with objective_event. (e.g., objective_event.tool_result) ### Unwrap Webhook Event - `UnwrapWebhookEvent` The envelope for an objective event webhook delivery. Contains timestamp, event type, and the webhook data payload. - `data: Data` The webhook data payload with flat top-level keys for agent, variation, objective, and event. - `agent: ResourceMetadata` Standard metadata for persistent, named resources (e.g., agents, tools, prompts) - `id: string` Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...") - `accountId: string` Account this resource belongs to for multi-tenant isolation (prefixed ULID) - `createdAt: string` Timestamp when this resource was created - `name: string` Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly - `profileId: string` ID of the actor (user or service account) that created this resource - `workspaceId: string` Workspace this resource belongs to for organizational grouping (prefixed ULID) - `externalId?: string` External ID for the resource (e.g., a workflow ID from an external system) - `labels?: Record` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `agentVariation: ResourceMetadata` Standard metadata for persistent, named resources (e.g., agents, tools, prompts) - `objective: OperationMetadata` Metadata for ephemeral operations and activities (e.g., objectives, executions, runs) - `id: string` Unique identifier for the operation (prefixed ULID, e.g., "obj_01HXK...") - `accountId: string` Account this operation belongs to for multi-tenant isolation (prefixed ULID) - `createdAt: string` Timestamp when this operation was created ULID includes timestamp information, but this explicit field enables easier querying - `profileId: string` ID of the actor (user or service account) that created this operation - `workspaceId: string` Workspace this operation belongs to for organizational grouping (prefixed ULID) - `externalId?: string` External ID for the operation (e.g., a workflow ID from an external system) - `labels?: Record` Arbitrary key-value pairs for categorization and filtering Examples: {"priority": "high", "source": "api", "workflow": "onboarding"} - `objectiveEvent: ObjectiveEvent` - `data: ObjectiveEventData` - `assistantMessage?: AssistantMessage` - `content?: string` - `toolCalls?: Array` - `arguments?: string` - `functionName?: string` - `tool?: CallableTool` CallableTool is a union that represents a tool that can be called by an agent. In Cadenya, a tool that is used within an agent objective might be a user-defined tool (IE: MCP, HTTP), another Agent (useful to separate context), or a Cadenya Tool (one Cadenya provides). - `agent?: ResourceMetadata` Standard metadata for persistent, named resources (e.g., agents, tools, prompts) - `cadenyaProvidedTool?: ResourceMetadata` Standard metadata for persistent, named resources (e.g., agents, tools, prompts) - `tool?: ResourceMetadata` Standard metadata for persistent, named resources (e.g., agents, tools, prompts) - `contextWindowCompacted?: ContextWindowCompacted` - `messagesCompacted?: number` Number of messages that were compacted - `newContextWindow?: ObjectiveContextWindowData` The new context window created by this compaction - `completionTokens?: number` A calculated value for how many completion tokens (output tokens) have been used in this context window - `objectiveId?: string` The objective's ID that this window belongs to - `previousWindowContinueInstructions?: string` The instructions for this window to continue from a previous window's chat history. - `promptTokens?: number` A calculated value for how many prompt tokens (input tokens) have been used in this context window - `sequence?: number` sequence is a numeric representation of which context window this is. Sequences are useful to perform a max(sequence) on in order to calculate how many context windows an objective has. - `strategies?: Array` The strategies that were applied during this compaction - `summary?: string` The summary generated by the summarization strategy, if used. - `error?: ObjectiveError` - `message?: string` - `type?: string` - `subObjectiveCreated?: SubObjectiveCreated` - `metadata?: OperationMetadata` Metadata for ephemeral operations and activities (e.g., objectives, executions, runs) - `toolApprovalRequested?: ToolApprovalRequested` - `toolCallId?: string` The ID of the objective tool call record. Use this ID with the ApproveToolCall or DenyToolCall RPCs to approve or deny the tool call. - `toolApproved?: ToolApproved` - `toolCallId?: string` The ID of the objective tool call record that was approved via the ApproveToolCall RPC. - `toolCalled?: ToolCalled` - `toolCallId?: string` The ID of the objective tool call record that was executed. - `toolDenied?: ToolDenied` - `memo?: string` The memo provided by the reviewer when denying the tool call. This is passed to the agent to provide further instructions. - `toolCallId?: string` The ID of the objective tool call record that was denied via the DenyToolCall RPC. - `toolError?: ToolError` - `message?: string` - `toolCallId?: string` The ID of the objective tool call record that encountered an error during execution. - `toolResult?: ToolResult` - `content?: string` - `toolCallId?: string` - `type?: string` - `userMessage?: UserMessage` - `content?: string` - `metadata: OperationMetadata` Metadata for ephemeral operations and activities (e.g., objectives, executions, runs) - `contextWindowId?: string` - `info?: ObjectiveEventInfo` - `createdBy?: Profile` Profile represents a human user at the account level. Profiles are account-scoped resources that can be associated with multiple workspaces through the Actor model. Authentication for profiles is handled via SSO/OAuth (WorkOS). - `metadata: AccountResourceMetadata` AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace. - `id: string` Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...") - `accountId: string` Account this resource belongs to for multi-tenant isolation (prefixed ULID) - `name: string` Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly - `profileId: string` - `externalId?: string` External ID for the resource (e.g., a workflow ID from an external system) - `labels?: Record` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `spec: ProfileSpec` ProfileSpec contains the profile-specific fields - `type: "PROFILE_TYPE_USER" | "PROFILE_TYPE_API_KEY" | "PROFILE_TYPE_SYSTEM"` Type is the type of profile. User's are humans, API keys are computers. You know the deal. - `"PROFILE_TYPE_USER"` - `"PROFILE_TYPE_API_KEY"` - `"PROFILE_TYPE_SYSTEM"` - `email?: string` Email address of the user (required, unique per account) - `name?: string` Display name for the user (e.g., "Bobby Tables") - `objective?: OperationMetadata` Metadata for ephemeral operations and activities (e.g., objectives, executions, runs) - `timestamp: string` - `type: string` The event type, prefixed with objective_event. (e.g., objective_event.tool_result)