# Webhooks ## `webhooks.unwrap() -> void` **** `` ### Example ```ruby require "cadenya" cadenya = Cadenya::Client.new(api_key: "My API Key") result = cadenya.webhooks.unwrap puts(result) ``` ## `webhooks.unsafe_unwrap() -> void` **** `` ### Example ```ruby require "cadenya" cadenya = Cadenya::Client.new(api_key: "My API Key") result = cadenya.webhooks.unsafe_unwrap puts(result) ``` ## Domain Types ### Unsafe Unwrap Webhook Event - `class UnsafeUnwrapWebhookEvent` The envelope for an objective event webhook delivery. Contains timestamp, event type, and the webhook data payload. - `data: Data{ agent, agent_variation, objective, objective_event}` 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...") - `account_id: String` Account this resource belongs to for multi-tenant isolation (prefixed ULID) - `created_at: Time` 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 - `profile_id: String` ID of the actor (user or service account) that created this resource - `workspace_id: String` Workspace this resource belongs to for organizational grouping (prefixed ULID) - `bundle_key: String` Optional bundle ownership key. When set, indicates the resource is managed by a configuration bundle identified by this key. Used by BulkWorkspaceResources.Apply to track which resources belong to which bundle for reconciliation / soft-delete on re-apply. - `external_id: String` External ID for the resource (e.g., a workflow ID from an external system) - `labels: Hash[Symbol, String]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `agent_variation: 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...") - `account_id: String` Account this operation belongs to for multi-tenant isolation (prefixed ULID) - `created_at: Time` Timestamp when this operation was created ULID includes timestamp information, but this explicit field enables easier querying - `profile_id: String` ID of the actor (user or service account) that created this operation - `workspace_id: String` Workspace this operation belongs to for organizational grouping (prefixed ULID) - `external_id: String` External ID for the operation (e.g., a workflow ID from an external system) - `labels: Hash[Symbol, String]` Arbitrary key-value pairs for categorization and filtering Examples: {"priority": "high", "source": "api", "workflow": "onboarding"} - `objective_event: ObjectiveEvent{ data, metadata, context_window_id, info}` - `data: ObjectiveEventData` - `assistant_message: AssistantMessage` - `content: String` - `tool_calls: Array[AssistantToolCall]` - `arguments: String` - `function_name: 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) - `cadenya_provided_tool: 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) - `cancelled: Cancelled{ message}` ObjectiveCancelled is the terminal event written when an objective is cancelled. After this event, the objective is super-terminal: no further iterations, compaction, or continuation are permitted. - `message: String` Optional human-readable note recorded at cancel time. Today the workflow sets "Cancelled" but this field leaves room for richer reasons (e.g. "Cancelled by user", "Cancelled by schedule sweep", "Credit balance exhausted"). - `context_window_compacted: ContextWindowCompacted` - `messages_compacted: Integer` Number of messages that were compacted - `new_context_window: ObjectiveContextWindowData` The new context window created by this compaction - `completion_tokens: Integer` A calculated value for how many completion tokens (output tokens) have been used in this context window - `objective_id: String` The objective's ID that this window belongs to - `previous_window_continue_instructions: String` The instructions for this window to continue from a previous window's chat history. - `prompt_tokens: Integer` A calculated value for how many prompt tokens (input tokens) have been used in this context window - `sequence: Integer` 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[String]` 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` - `finalized: Finalized{ output}` ObjectiveFinalized is the terminal event written when an objective is finalized. After this event, the objective is super-terminal: no further iterations, compaction, or continuation are permitted. - `output: untyped` If the objective was created with an output schema, and the agent successfully completed the objective, this field will contain the structured output of the objective. - `memory_read: MemoryRead` MemoryRead is emitted each time the agent resolves a key against the memory stack and loads an entry. Lookups that miss (key not found in any layer) do not emit this event. - `memory_entry_id: String` The specific entry that was read. - `memory_layer_id: String` The layer the entry resolved to. The top-most layer that contained the key — other layers beneath it that also contained the key are shadowed and not referenced here. - `message: String` Human-readable description of the read, set by the runtime. For example: "Loaded skill", "Resolved context key". Not machine-parsed; intended for UI display alongside the other events in an objective's timeline. - `sub_agent_spawned: SubAgentSpawned` - `agent: 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) - `task: String` - `sub_agent_updated: SubAgentUpdated` - `agent: BareMetadata` BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves. - `id: String` - `name: String` Human-readable name of the referenced resource, populated by the server on reads for convenience. Absent on references to resources that do not have a name (e.g., objective tasks). - `message: String` - `objective: BareMetadata` BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves. - `status: :STATUS_UNSPECIFIED | :STATUS_PENDING | :STATUS_RUNNING | 3 more` - `:STATUS_UNSPECIFIED` - `:STATUS_PENDING` - `:STATUS_RUNNING` - `:STATUS_COMPLETED` - `:STATUS_FAILED` - `:STATUS_CANCELLED` - `tool_approval_requested: ToolApprovalRequested` - `tool_call_id: 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. - `tool_approved: ToolApproved` - `tool_call_id: String` The ID of the objective tool call record that was approved via the ApproveToolCall RPC. - `tool_called: ToolCalled` - `tool_call_id: String` The ID of the objective tool call record that was executed. - `tool_denied: ToolDenied` - `memo: String` The memo provided by the reviewer when denying the tool call. This is passed to the agent to provide further instructions. - `tool_call_id: String` The ID of the objective tool call record that was denied via the DenyToolCall RPC. - `tool_error: ToolError` - `message: String` - `tool_call_id: String` The ID of the objective tool call record that encountered an error during execution. - `tool_result: ToolResult` - `content: String` - `tool_call_id: String` - `type: String` - `user_message: UserMessage` - `content: String` - `metadata: OperationMetadata` Metadata for ephemeral operations and activities (e.g., objectives, executions, runs) - `context_window_id: String` - `info: ObjectiveEventInfo` - `created_by: Profile` A profile identifies a user or non-human principal (such as an API key) at the account level. Profiles are account-scoped and can be granted access to multiple workspaces. - `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...") - `account_id: 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 - `profile_id: String` - `external_id: String` External ID for the resource (e.g., a workflow ID from an external system) - `labels: Hash[Symbol, String]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `spec: ProfileSpec` Configuration for a profile. - `type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM` Whether this profile represents a human user, an API key, or a system principal. - `:PROFILE_TYPE_UNSPECIFIED` - `:PROFILE_TYPE_USER` - `:PROFILE_TYPE_API_KEY` - `:PROFILE_TYPE_SYSTEM` - `email: String` Email address of the profile. Required and unique within an account for user profiles. - `name: String` Display name (e.g., "Bobby Tables"). - `objective: OperationMetadata` Metadata for ephemeral operations and activities (e.g., objectives, executions, runs) - `timestamp: Time` - `type: String` The event type, prefixed with objective_event. (e.g., objective_event.tool_result) ### Unwrap Webhook Event - `class UnwrapWebhookEvent` The envelope for an objective event webhook delivery. Contains timestamp, event type, and the webhook data payload. - `data: Data{ agent, agent_variation, objective, objective_event}` 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...") - `account_id: String` Account this resource belongs to for multi-tenant isolation (prefixed ULID) - `created_at: Time` 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 - `profile_id: String` ID of the actor (user or service account) that created this resource - `workspace_id: String` Workspace this resource belongs to for organizational grouping (prefixed ULID) - `bundle_key: String` Optional bundle ownership key. When set, indicates the resource is managed by a configuration bundle identified by this key. Used by BulkWorkspaceResources.Apply to track which resources belong to which bundle for reconciliation / soft-delete on re-apply. - `external_id: String` External ID for the resource (e.g., a workflow ID from an external system) - `labels: Hash[Symbol, String]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `agent_variation: 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...") - `account_id: String` Account this operation belongs to for multi-tenant isolation (prefixed ULID) - `created_at: Time` Timestamp when this operation was created ULID includes timestamp information, but this explicit field enables easier querying - `profile_id: String` ID of the actor (user or service account) that created this operation - `workspace_id: String` Workspace this operation belongs to for organizational grouping (prefixed ULID) - `external_id: String` External ID for the operation (e.g., a workflow ID from an external system) - `labels: Hash[Symbol, String]` Arbitrary key-value pairs for categorization and filtering Examples: {"priority": "high", "source": "api", "workflow": "onboarding"} - `objective_event: ObjectiveEvent{ data, metadata, context_window_id, info}` - `data: ObjectiveEventData` - `assistant_message: AssistantMessage` - `content: String` - `tool_calls: Array[AssistantToolCall]` - `arguments: String` - `function_name: 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) - `cadenya_provided_tool: 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) - `cancelled: Cancelled{ message}` ObjectiveCancelled is the terminal event written when an objective is cancelled. After this event, the objective is super-terminal: no further iterations, compaction, or continuation are permitted. - `message: String` Optional human-readable note recorded at cancel time. Today the workflow sets "Cancelled" but this field leaves room for richer reasons (e.g. "Cancelled by user", "Cancelled by schedule sweep", "Credit balance exhausted"). - `context_window_compacted: ContextWindowCompacted` - `messages_compacted: Integer` Number of messages that were compacted - `new_context_window: ObjectiveContextWindowData` The new context window created by this compaction - `completion_tokens: Integer` A calculated value for how many completion tokens (output tokens) have been used in this context window - `objective_id: String` The objective's ID that this window belongs to - `previous_window_continue_instructions: String` The instructions for this window to continue from a previous window's chat history. - `prompt_tokens: Integer` A calculated value for how many prompt tokens (input tokens) have been used in this context window - `sequence: Integer` 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[String]` 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` - `finalized: Finalized{ output}` ObjectiveFinalized is the terminal event written when an objective is finalized. After this event, the objective is super-terminal: no further iterations, compaction, or continuation are permitted. - `output: untyped` If the objective was created with an output schema, and the agent successfully completed the objective, this field will contain the structured output of the objective. - `memory_read: MemoryRead` MemoryRead is emitted each time the agent resolves a key against the memory stack and loads an entry. Lookups that miss (key not found in any layer) do not emit this event. - `memory_entry_id: String` The specific entry that was read. - `memory_layer_id: String` The layer the entry resolved to. The top-most layer that contained the key — other layers beneath it that also contained the key are shadowed and not referenced here. - `message: String` Human-readable description of the read, set by the runtime. For example: "Loaded skill", "Resolved context key". Not machine-parsed; intended for UI display alongside the other events in an objective's timeline. - `sub_agent_spawned: SubAgentSpawned` - `agent: 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) - `task: String` - `sub_agent_updated: SubAgentUpdated` - `agent: BareMetadata` BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves. - `id: String` - `name: String` Human-readable name of the referenced resource, populated by the server on reads for convenience. Absent on references to resources that do not have a name (e.g., objective tasks). - `message: String` - `objective: BareMetadata` BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves. - `status: :STATUS_UNSPECIFIED | :STATUS_PENDING | :STATUS_RUNNING | 3 more` - `:STATUS_UNSPECIFIED` - `:STATUS_PENDING` - `:STATUS_RUNNING` - `:STATUS_COMPLETED` - `:STATUS_FAILED` - `:STATUS_CANCELLED` - `tool_approval_requested: ToolApprovalRequested` - `tool_call_id: 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. - `tool_approved: ToolApproved` - `tool_call_id: String` The ID of the objective tool call record that was approved via the ApproveToolCall RPC. - `tool_called: ToolCalled` - `tool_call_id: String` The ID of the objective tool call record that was executed. - `tool_denied: ToolDenied` - `memo: String` The memo provided by the reviewer when denying the tool call. This is passed to the agent to provide further instructions. - `tool_call_id: String` The ID of the objective tool call record that was denied via the DenyToolCall RPC. - `tool_error: ToolError` - `message: String` - `tool_call_id: String` The ID of the objective tool call record that encountered an error during execution. - `tool_result: ToolResult` - `content: String` - `tool_call_id: String` - `type: String` - `user_message: UserMessage` - `content: String` - `metadata: OperationMetadata` Metadata for ephemeral operations and activities (e.g., objectives, executions, runs) - `context_window_id: String` - `info: ObjectiveEventInfo` - `created_by: Profile` A profile identifies a user or non-human principal (such as an API key) at the account level. Profiles are account-scoped and can be granted access to multiple workspaces. - `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...") - `account_id: 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 - `profile_id: String` - `external_id: String` External ID for the resource (e.g., a workflow ID from an external system) - `labels: Hash[Symbol, String]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `spec: ProfileSpec` Configuration for a profile. - `type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM` Whether this profile represents a human user, an API key, or a system principal. - `:PROFILE_TYPE_UNSPECIFIED` - `:PROFILE_TYPE_USER` - `:PROFILE_TYPE_API_KEY` - `:PROFILE_TYPE_SYSTEM` - `email: String` Email address of the profile. Required and unique within an account for user profiles. - `name: String` Display name (e.g., "Bobby Tables"). - `objective: OperationMetadata` Metadata for ephemeral operations and activities (e.g., objectives, executions, runs) - `timestamp: Time` - `type: String` The event type, prefixed with objective_event. (e.g., objective_event.tool_result)