Webhooks

ModelsExpand Collapse

UnsafeUnwrapWebhookEvent 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: ResourceMetadata { id, accountId, createdAt, 6 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

formatdate-time

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)

bundleKey: optional 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.

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: ResourceMetadata { id, accountId, createdAt, 6 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

formatdate-time

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)

bundleKey: optional 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”}

objective: OperationMetadata { 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

formatdate-time

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: ObjectiveEventData { assistantMessage, cancelled, contextWindowCompacted, 13 more }

assistantMessage: optional AssistantMessage { content, toolCalls }

content: optional string

toolCalls: optional array of AssistantToolCall { arguments, functionName, tool }

arguments: optional string

functionName: optional string

tool: optional CallableTool { 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 ResourceMetadata { id, accountId, createdAt, 6 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

formatdate-time

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)

bundleKey: optional 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”}

cadenyaProvidedTool: optional ResourceMetadata { id, accountId, createdAt, 6 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

formatdate-time

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)

bundleKey: optional 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”}

tool: optional ResourceMetadata { id, accountId, createdAt, 6 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

formatdate-time

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)

bundleKey: optional 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”}

cancelled: optional object { 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: optional 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”).

contextWindowCompacted: optional ContextWindowCompacted { messagesCompacted, newContextWindow, strategies, summary }

messagesCompacted: optional number

Number of messages that were compacted

formatint32

newContextWindow: optional ObjectiveContextWindowData { 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

formatint32

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

formatint32

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.

formatint32

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 ObjectiveError { message, type }

message: optional string

type: optional string

finalized: optional object { 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: optional unknown

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.

memoryRead: optional MemoryRead { memoryEntryId, memoryLayerId, message }

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.

memoryEntryId: optional string

The specific entry that was read.

memoryLayerId: optional 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: optional 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.

subAgentSpawned: optional SubAgentSpawned { agent, objective, task }

agent: optional ResourceMetadata { id, accountId, createdAt, 6 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

formatdate-time

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)

bundleKey: optional 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”}

objective: optional OperationMetadata { 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

formatdate-time

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”}

task: optional string

subAgentUpdated: optional SubAgentUpdated { agent, message, objective, status }

agent: optional BareMetadata { id, name }

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: optional 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: optional string

objective: optional BareMetadata { id, name }

id: optional 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).

status: optional "STATUS_UNSPECIFIED" or "STATUS_PENDING" or "STATUS_RUNNING" or 3 more

formatenum

One of the following:

"STATUS_UNSPECIFIED"

"STATUS_PENDING"

"STATUS_RUNNING"

"STATUS_COMPLETED"

"STATUS_FAILED"

"STATUS_CANCELLED"

toolApprovalRequested: optional ToolApprovalRequested { 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 ToolApproved { toolCallId }

toolCallId: optional string

The ID of the objective tool call record that was approved via the ApproveToolCall RPC.

toolCalled: optional ToolCalled { toolCallId }

toolCallId: optional string

The ID of the objective tool call record that was executed.

toolDenied: optional ToolDenied { 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 ToolError { message, toolCallId }

message: optional string

toolCallId: optional string

The ID of the objective tool call record that encountered an error during execution.

toolResult: optional ToolResult { content, toolCallId }

content: optional string

toolCallId: optional string

type: optional string

userMessage: optional UserMessage { content }

content: optional string

metadata: OperationMetadata { 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

formatdate-time

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 ObjectiveEventInfo { createdBy, objective }

createdBy: optional Profile { metadata, spec }

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 { 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)

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: ProfileSpec { type, email, name }

Configuration for a profile.

type: "PROFILE_TYPE_UNSPECIFIED" or "PROFILE_TYPE_USER" or "PROFILE_TYPE_API_KEY" or "PROFILE_TYPE_SYSTEM"

Whether this profile represents a human user, an API key, or a system principal.

formatenum

One of the following:

"PROFILE_TYPE_UNSPECIFIED"

"PROFILE_TYPE_USER"

"PROFILE_TYPE_API_KEY"

"PROFILE_TYPE_SYSTEM"

email: optional string

Email address of the profile. Required and unique within an account for user profiles.

Display name (e.g., “Bobby Tables”).

objective: optional OperationMetadata { 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

formatdate-time

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)

Webhooks

Unwrap

Unsafe Unwrap

ModelsExpand Collapse