Skip to main content

llm.tool_call_approval_required

A routed tool call is parked for human approval with a decision deadline.

Owner: Delegation and approvals. Direction: Travila → your endpoint (outgoing).

The receiver gets an HTTP POST webhook request whose body is the event payload itself. JSON uses protobuf field names (snake_case). See delivery headers and signature verification before accepting it.

Operations that can produce this event​

These operations can start the generation workflow that emits this event. Receiving a successful API response does not establish that every event will be produced or delivered.

Payload fields​

FieldTypePresenceMeaning
event_contextEventContextOptionalEvent provenance and routing metadata associated with the emitted event.
tool_callToolCallOptionalTool-call snapshot before a result is available, including its identity, name, server and arguments. For llm.tool_call_started the status is EXECUTING; for llm.tool_call_approval_required it is REQUIRES_CONFIRMATION and requires_approval_at is the decision deadline. result_json is unset.

Full payload model: ToolCallStartedEvent.

Example​

Illustrative payload, not a captured delivery. Identifiers, tool names and outcomes are examples; omitted fields depend on the event.

{
  "event_context": {
    "event_name": "llm.tool_call_approval_required",
    "version": "1.0",
    "event_id": "d3b842c8-b19a-4205-a06f-c57cbf313584",
    "correlation_id": "9d4c2e1f-27b1-4304-ae54-af7fe876df31",
    "emitted_at": "2026-09-16T12:00:00Z",
    "caller_key": "tenant-demo:b81d5345-c1f9-4fb9-b558-a6327c75b842",
    "tenant_id": "tenant-demo",
    "project_id": "default"
  },
  "tool_call": {
    "id": "call_123",
    "name": "send_briefing",
    "server_id": "briefing-tools",
    "arguments_json": {
      "conversation_id": "b81d5345-c1f9-4fb9-b558-a6327c75b842"
    },
    "status": "TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION",
    "requires_approval_at": "2026-09-16T12:05:00Z"
  }
}

The tool call has not been dispatched. Its status is TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION, and requires_approval_at is the decision deadline. Reconcile with pending approvals, then use submit tool approvals.

Download the public reference contract for this event schema and its named example.

Document: DOC-API-EVENT-llm-tool-call-approval-required.