Kapso provides programmatic ways to interact with your agents and the platform through its API and webhooks.

​
Kapso API

Kapso offers an API for external systems to interact with projects and agents. Key capabilities include triggering agent executions, retrieving data, and potentially managing resources. Authentication relies on API Keys found in your Project settings. See the full API Reference for details.

​
Agent Webhooks

Webhooks allow two-way communication: your systems can trigger Kapso agents, and Kapso agents can notify your systems.

​
Incoming Webhooks (Triggering Agents)

Use incoming webhooks to start an agent’s execution flow from your application (e.g., backend, CRM).

  • Endpoint: Each agent has a unique webhook URL.

    POST https://app.kapso.ai/api/v1/agents/{AGENT_ID}/executions

  • Authentication: Include your Project API Key in the X-API-Key request header.

    X-API-Key: your-project-api-key

  • Request Body (Optional): Send initial data in the JSON payload.

    {
  "message": "Optional initial message for the agent",
  "phone_number": "1234567890" // Optional identifier
}

  • Example (Node.js):

    const agentWebhookUrl = 'https://app.kapso.ai/api/v1/agents/YOUR_AGENT_ID/executions';
const apiKey = 'YOUR_PROJECT_API_KEY';

const payload = JSON.stringify({
  message: 'Hello agent!',
  phone_number: '1987654321'
});

fetch(agentWebhookUrl, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': apiKey
  },
  body: payload
})
.then(response => response.json())
.then(data => console.log('Agent execution started:', data))
.catch(error => console.error('Error triggering agent:', error));

​
Outbound Webhooks (Agent Notifications)

Configure outbound webhooks for your agent to send notifications to your external systems when specific events occur.

  • Configuration: Set up webhook URLs and select the events to subscribe to in the agent’s “API & Webhooks” settings. You’ll also configure a Secret Key for verifying incoming requests.

  • Supported Events:

    • agent_execution_started: Triggered when a new agent execution begins.
    • agent_execution_ended: Triggered when an agent execution completes (successfully or with errors).
    • agent_execution_handoff: Triggered when the agent enters a handoff state (e.g., via a HandoffNode).

  • Verification: Kapso includes an X-Webhook-Signature header in each request. This is an HMAC SHA-256 signature of the raw request body, generated using the Secret Key you configured for the webhook. Verify this signature in your endpoint to ensure the request genuinely came from Kapso.

  • Example Payload (Standard Events):

    {
  "event": "agent_execution_started", // or "agent_execution_ended"
  "agent_execution": {
    "id": "execution-id",
    "started_at": "2023-01-01T12:00:00Z",
    "agent_id": "agent-id"
  },
  "agent": {
    "id": "agent-id",
    "name": "My Support Agent"
  }
  // Additional data might be included depending on the event
}

  • Example Payload (Handoff Event):

    {
  "event": "agent_execution_handoff",
  "agent_execution": {
    "id": "execution-id",
    "started_at": "2023-01-01T12:00:00Z",
    "agent_id": "agent-id"
  },
  "agent": {
    "id": "agent-id",
    "name": "My Support Agent"
  },
  "handoff": {
    "node_name": "Customer Support Handoff Node", // Name of the handoff node in the graph
    "handoff_reason": "Agent identified need for human assistance" // Optional reason provided by the agent
  }
}