# Webhooks ## Domain Types ### Unsafe Unwrap Webhook Event - `unsafe_unwrap_webhook_event: object { data, timestamp, type }` The envelope for an objective event webhook delivery. Contains timestamp, event type, and the webhook data payload. - `data: object { agent, agentVariation, objective, objectiveEvent }` The webhook data payload with flat top-level keys for agent, variation, objective, and event. - `agent: object { id, accountId, createdAt, 5 more }` 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: optional string` External ID for the resource (e.g., a workflow ID from an external system) - `labels: optional map[string]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `agentVariation: object { id, accountId, createdAt, 5 more }` 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: optional string` External ID for the resource (e.g., a workflow ID from an external system) - `labels: optional map[string]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `objective: object { id, accountId, createdAt, 4 more }` 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: optional string` External ID for the operation (e.g., a workflow ID from an external system) - `labels: optional map[string]` Arbitrary key-value pairs for categorization and filtering Examples: {"priority": "high", "source": "api", "workflow": "onboarding"} - `objectiveEvent: object { data, metadata, contextWindowId, info }` - `data: object { assistantMessage, contextWindowCompacted, error, 9 more }` - `assistantMessage: optional object { content, toolCalls }` - `content: optional string` - `toolCalls: optional array of AssistantToolCall` - `arguments: optional string` - `functionName: optional string` - `tool: optional object { agent, cadenyaProvidedTool, tool }` 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: optional object { id, accountId, createdAt, 5 more }` 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: optional string` External ID for the resource (e.g., a workflow ID from an external system) - `labels: optional map[string]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `cadenyaProvidedTool: optional object { id, accountId, createdAt, 5 more }` 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: optional string` External ID for the resource (e.g., a workflow ID from an external system) - `labels: optional map[string]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `tool: optional object { id, accountId, createdAt, 5 more }` 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: optional string` External ID for the resource (e.g., a workflow ID from an external system) - `labels: optional map[string]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `contextWindowCompacted: optional object { messagesCompacted, newContextWindow, strategies, summary }` - `messagesCompacted: optional number` Number of messages that were compacted - `newContextWindow: optional object { completionTokens, objectiveId, previousWindowContinueInstructions, 2 more }` The new context window created by this compaction - `completionTokens: optional number` A calculated value for how many completion tokens (output tokens) have been used in this context window - `objectiveId: optional string` The objective's ID that this window belongs to - `previousWindowContinueInstructions: optional string` The instructions for this window to continue from a previous window's chat history. - `promptTokens: optional number` A calculated value for how many prompt tokens (input tokens) have been used in this context window - `sequence: optional 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: optional array of string` The strategies that were applied during this compaction - `summary: optional string` The summary generated by the summarization strategy, if used. - `error: optional object { message, type }` - `message: optional string` - `type: optional string` - `subObjectiveCreated: optional object { metadata }` - `metadata: optional object { id, accountId, createdAt, 4 more }` 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: optional string` External ID for the operation (e.g., a workflow ID from an external system) - `labels: optional map[string]` Arbitrary key-value pairs for categorization and filtering Examples: {"priority": "high", "source": "api", "workflow": "onboarding"} - `toolApprovalRequested: optional object { toolCallId }` - `toolCallId: optional 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: optional object { toolCallId }` - `toolCallId: optional string` The ID of the objective tool call record that was approved via the ApproveToolCall RPC. - `toolCalled: optional object { toolCallId }` - `toolCallId: optional string` The ID of the objective tool call record that was executed. - `toolDenied: optional object { memo, toolCallId }` - `memo: optional string` The memo provided by the reviewer when denying the tool call. This is passed to the agent to provide further instructions. - `toolCallId: optional string` The ID of the objective tool call record that was denied via the DenyToolCall RPC. - `toolError: optional object { message, toolCallId }` - `message: optional string` - `toolCallId: optional string` The ID of the objective tool call record that encountered an error during execution. - `toolResult: optional object { content, toolCallId }` - `content: optional string` - `toolCallId: optional string` - `type: optional string` - `userMessage: optional object { content }` - `content: optional string` - `metadata: object { id, accountId, createdAt, 4 more }` 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: optional string` External ID for the operation (e.g., a workflow ID from an external system) - `labels: optional map[string]` Arbitrary key-value pairs for categorization and filtering Examples: {"priority": "high", "source": "api", "workflow": "onboarding"} - `contextWindowId: optional string` - `info: optional object { createdBy, objective }` - `createdBy: optional object { metadata, spec }` 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: object { id, accountId, name, 3 more }` 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: optional string` External ID for the resource (e.g., a workflow ID from an external system) - `labels: optional map[string]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `spec: object { type, email, name }` ProfileSpec contains the profile-specific fields - `type: "PROFILE_TYPE_USER" or "PROFILE_TYPE_API_KEY" or "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: optional string` Email address of the user (required, unique per account) - `name: optional string` Display name for the user (e.g., "Bobby Tables") - `objective: optional object { id, accountId, createdAt, 4 more }` 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: optional string` External ID for the operation (e.g., a workflow ID from an external system) - `labels: optional map[string]` Arbitrary key-value pairs for categorization and filtering Examples: {"priority": "high", "source": "api", "workflow": "onboarding"} - `timestamp: string` - `type: string` The event type, prefixed with objective_event. (e.g., objective_event.tool_result) ### Unwrap Webhook Event - `unwrap_webhook_event: object { data, timestamp, type }` The envelope for an objective event webhook delivery. Contains timestamp, event type, and the webhook data payload. - `data: object { agent, agentVariation, objective, objectiveEvent }` The webhook data payload with flat top-level keys for agent, variation, objective, and event. - `agent: object { id, accountId, createdAt, 5 more }` 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: optional string` External ID for the resource (e.g., a workflow ID from an external system) - `labels: optional map[string]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `agentVariation: object { id, accountId, createdAt, 5 more }` 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: optional string` External ID for the resource (e.g., a workflow ID from an external system) - `labels: optional map[string]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `objective: object { id, accountId, createdAt, 4 more }` 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: optional string` External ID for the operation (e.g., a workflow ID from an external system) - `labels: optional map[string]` Arbitrary key-value pairs for categorization and filtering Examples: {"priority": "high", "source": "api", "workflow": "onboarding"} - `objectiveEvent: object { data, metadata, contextWindowId, info }` - `data: object { assistantMessage, contextWindowCompacted, error, 9 more }` - `assistantMessage: optional object { content, toolCalls }` - `content: optional string` - `toolCalls: optional array of AssistantToolCall` - `arguments: optional string` - `functionName: optional string` - `tool: optional object { agent, cadenyaProvidedTool, tool }` 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: optional object { id, accountId, createdAt, 5 more }` 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: optional string` External ID for the resource (e.g., a workflow ID from an external system) - `labels: optional map[string]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `cadenyaProvidedTool: optional object { id, accountId, createdAt, 5 more }` 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: optional string` External ID for the resource (e.g., a workflow ID from an external system) - `labels: optional map[string]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `tool: optional object { id, accountId, createdAt, 5 more }` 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: optional string` External ID for the resource (e.g., a workflow ID from an external system) - `labels: optional map[string]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `contextWindowCompacted: optional object { messagesCompacted, newContextWindow, strategies, summary }` - `messagesCompacted: optional number` Number of messages that were compacted - `newContextWindow: optional object { completionTokens, objectiveId, previousWindowContinueInstructions, 2 more }` The new context window created by this compaction - `completionTokens: optional number` A calculated value for how many completion tokens (output tokens) have been used in this context window - `objectiveId: optional string` The objective's ID that this window belongs to - `previousWindowContinueInstructions: optional string` The instructions for this window to continue from a previous window's chat history. - `promptTokens: optional number` A calculated value for how many prompt tokens (input tokens) have been used in this context window - `sequence: optional 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: optional array of string` The strategies that were applied during this compaction - `summary: optional string` The summary generated by the summarization strategy, if used. - `error: optional object { message, type }` - `message: optional string` - `type: optional string` - `subObjectiveCreated: optional object { metadata }` - `metadata: optional object { id, accountId, createdAt, 4 more }` 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: optional string` External ID for the operation (e.g., a workflow ID from an external system) - `labels: optional map[string]` Arbitrary key-value pairs for categorization and filtering Examples: {"priority": "high", "source": "api", "workflow": "onboarding"} - `toolApprovalRequested: optional object { toolCallId }` - `toolCallId: optional 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: optional object { toolCallId }` - `toolCallId: optional string` The ID of the objective tool call record that was approved via the ApproveToolCall RPC. - `toolCalled: optional object { toolCallId }` - `toolCallId: optional string` The ID of the objective tool call record that was executed. - `toolDenied: optional object { memo, toolCallId }` - `memo: optional string` The memo provided by the reviewer when denying the tool call. This is passed to the agent to provide further instructions. - `toolCallId: optional string` The ID of the objective tool call record that was denied via the DenyToolCall RPC. - `toolError: optional object { message, toolCallId }` - `message: optional string` - `toolCallId: optional string` The ID of the objective tool call record that encountered an error during execution. - `toolResult: optional object { content, toolCallId }` - `content: optional string` - `toolCallId: optional string` - `type: optional string` - `userMessage: optional object { content }` - `content: optional string` - `metadata: object { id, accountId, createdAt, 4 more }` 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: optional string` External ID for the operation (e.g., a workflow ID from an external system) - `labels: optional map[string]` Arbitrary key-value pairs for categorization and filtering Examples: {"priority": "high", "source": "api", "workflow": "onboarding"} - `contextWindowId: optional string` - `info: optional object { createdBy, objective }` - `createdBy: optional object { metadata, spec }` 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: object { id, accountId, name, 3 more }` 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: optional string` External ID for the resource (e.g., a workflow ID from an external system) - `labels: optional map[string]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `spec: object { type, email, name }` ProfileSpec contains the profile-specific fields - `type: "PROFILE_TYPE_USER" or "PROFILE_TYPE_API_KEY" or "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: optional string` Email address of the user (required, unique per account) - `name: optional string` Display name for the user (e.g., "Bobby Tables") - `objective: optional object { id, accountId, createdAt, 4 more }` 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: optional string` External ID for the operation (e.g., a workflow ID from an external system) - `labels: optional map[string]` Arbitrary key-value pairs for categorization and filtering Examples: {"priority": "high", "source": "api", "workflow": "onboarding"} - `timestamp: string` - `type: string` The event type, prefixed with objective_event. (e.g., objective_event.tool_result)