On conversation update
POST /api/v1/webhooks/conversations
Webhook callback for when a conversation starts, pauses, resumes, or deletes. The ConversationInfo.agent field is an AgentBase discriminated union so both Faheem Code (Agent) and ACP (ACPAgent) payloads are accepted on this single endpoint.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | Unique conversation ID |
workspace | BaseWorkspace | yes | Workspace used by the agent to execute commands and read/write files. Not the process working directory. |
persistence_dir | `string | null` | no |
max_iterations | integer | no | Maximum number of iterations the agent can perform in a single run. |
stuck_detection | boolean | no | Whether to enable stuck detection for the agent. |
execution_status | ConversationExecutionStatus | no | — |
confirmation_policy | ConfirmationPolicyBase | no | — |
security_analyzer | `SecurityAnalyzerBase | null` | no |
activated_knowledge_skills | string[] | no | List of activated knowledge skills name |
invoked_skills | string[] | no | Names of progressive-disclosure skills explicitly invoked via the invoke_skill tool. |
blocked_actions | object | no | Actions blocked by PreToolUse hooks, keyed by action ID |
blocked_messages | object | no | Messages blocked by UserPromptSubmit hooks, keyed by message ID |
last_user_message_id | `string | null` | no |
leaf_event_id | `string | null` | no |
stats | ConversationStats | no | Conversation statistics for tracking LLM metrics |
secret_registry | SecretRegistry | no | Registry for handling secrets and sensitive data |
agent_state | object | no | Dictionary for agent-specific runtime state that persists across iterations. |
hook_config | `HookConfig-Input | null` | no |
title | `string | null` | no |
metrics | `MetricsSnapshot | null` | no |
created_at | string | no | — |
updated_at | string | no | — |
forked_from_conversation_id | `string | null` | no |
forked_from_event_id | `string | null` | no |
parent_conversation_id | `string | null` | no |
sub_conversation_ids | string[] | no | IDs of conversations naming this one as their parent. Derived from the server catalog; empty on webhook payloads. Name mirrors the Cloud API field. |
tags | object | no | Key-value tags for the conversation. Keys must be lowercase alphanumeric. Values are arbitrary strings up to 256 characters. |
current_model_id | `string | null` | no |
available_models | ACPModelInfo[] | no | Models the ACP server offers for this session, lifted off ACPAgent.available_models (the models.availableModels field on the ACP session response). Each entry carries a model_id plus an optional name/description. Surfaced verbatim so clients can render a model picker and resolve current_model_id to a display label themselves — the server does no name curation. Empty for ACP servers that don't surface the (UNSTABLE) capability and for native Faheem Code agents. Client contract: current_model_id is NOT guaranteed to be a member — a forced acp_model override may name a model absent from the list — so treat a miss as 'show the raw id'. Some entries are opaque aliases whose human identity lives in description (e.g. claude-agent-acp's "default" -> "Opus 4.7 with 1M context · ..."). |
supports_runtime_model_switch | boolean | no | Whether a live, mid-conversation model switch will be attempted for this conversation — tells the inline picker whether to offer a live-switch control. Mirrors the SDK's switch gate: True for known switch-capable providers; False for unknown/custom ACP servers because their generic config writes are not guaranteed live-switch primitives. False for native Faheem Code agents, for a known provider that declares no support, and before the conversation has started a session. |
launched_agent_profile | `LaunchedAgentProfile | null` | no |
agent | AgentBase | yes | The agent running in the conversation. |
client_tools | ClientToolSpec[] | no | Client-defined tool specs registered for this conversation. Surfaced so that a client re-attaching by conversation id can register the dynamic ClientAction_* action types before syncing persisted events, avoiding 'Unknown kind' deserialization errors. |
Responses
| Status | Description |
|---|---|
200 | Successful Response |
422 | Validation Error |
Response body
| Field | Type | Required | Description |
|---|---|---|---|
success | boolean | no | — |
Operation ID: on_conversation_update_api_v1_webhooks_conversations_post