AI agents

AI action pending approval

ai.action.pending

Fires when an AI agent proposes a sensitive action (e.g. `block_contact`, `close_conversation`, `delete_messages`) that requires human approval before execution. The action stays pending with no automatic timeout until an operator resolves it via `POST /v1/ai-pending-actions/{id}/approve` or `/reject`, after which `ai.action.approved` or `ai.action.rejected` fires.

HTTP request

AISAR sends a signed POST request to your webhook_url:

http

POST {webhook_url}
Content-Type: application/json
X-AISAR-Signature: sha256=...

{
  "event": "ai.action.pending",
  "event_id": "evt_01JXXXXXXXXXXXXXXXXXXXXX",
  "timestamp": "2026-05-11T12:00:00.000000Z",
  "company_id": 1,
  "data": {
    "ai_action": {
      "id": 999,
      "company_id": 1,
      "conversation_id": 45,
      "tool_key": "block_contact",
      "ai_agent_instance_id": 7,
      "approval_status": "pending",
      "comment": "AI agent proposed to block contact (reason: spam)",
      "reason": "Contact is sending spam content",
      "rejected_reason": null,
      "approved_by_user_id": null,
      "rejected_by_user_id": null,
      "execution_result": null,
      "created_at": "2026-05-11T12:00:00.000000Z",
      "resolved_at": null
    }
  }
}

The X-AISAR-Signature header carries an HMAC-SHA256 signature of the request body — use it to verify the request came from AISAR.

Example payload

json

{
  "event": "ai.action.pending",
  "event_id": "evt_01JXXXXXXXXXXXXXXXXXXXXX",
  "timestamp": "2026-05-11T12:00:00.000000Z",
  "company_id": 1,
  "data": {
    "ai_action": {
      "id": 999,
      "company_id": 1,
      "conversation_id": 45,
      "tool_key": "block_contact",
      "ai_agent_instance_id": 7,
      "approval_status": "pending",
      "comment": "AI agent proposed to block contact (reason: spam)",
      "reason": "Contact is sending spam content",
      "rejected_reason": null,
      "approved_by_user_id": null,
      "rejected_by_user_id": null,
      "execution_result": null,
      "created_at": "2026-05-11T12:00:00.000000Z",
      "resolved_at": null
    }
  }
}

Payload fields

Field	Type	Description
`ai_action.id`	`integer`	Proposed action ID — use it with the approve/reject API
`ai_action.company_id`	`integer`	Company ID
`ai_action.conversation_id`	`integer`	Conversation the AI was working in
`ai_action.tool_key`	`string`	Tool the agent invoked. Currently: `block_contact`, `close_conversation`, `delete_messages`
`ai_action.ai_agent_instance_id`	`integer`	Configured agent instance that proposed the action
`ai_action.approval_status`	`string`	Always `pending` for this event
`ai_action.comment`	`string`	Short human-readable summary emitted by the agent
`ai_action.reason`	`string\|null`	Free-form reason supplied by the LLM
`ai_action.created_at`	`string`	When the action was proposed (ISO 8601)
`ai_action.resolved_at`	`null`	Always null at this stage