Kapso provides powerful programmatic interfaces to integrate your agents with external systems, enabling automated workflows and real-time communication.

​
API Overview

The Kapso API enables you to:

  • Trigger agent executions programmatically
  • Retrieve execution status and results
  • Manage agent configurations
  • Access conversation history

​
Authentication

All API requests require authentication using your Project API Key:

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

Find your API keys in your Project settings under “API Keys”. Keep these keys secure and never expose them in client-side code.

For complete endpoint documentation, see the API Reference.

​
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 your agents to send real-time notifications to your systems when important events occur during execution.

​
Configuration

  1. Navigate to your agent’s “API & Webhooks” settings
  2. Add webhook endpoints for the events you want to monitor
  3. Configure a Secret Key for request verification
  4. Select which events to subscribe to

​
Supported Events

Execution Started

agent_execution_started

Fired when an agent begins processing

Execution Ended

agent_execution_ended

Fired when an agent completes successfully

Execution Failed

agent_execution_failed

Fired when an agent encounters an error

Handoff Required

agent_execution_handoff

Fired when human intervention is needed

​
Security & Verification

Every webhook request includes an X-Webhook-Signature header containing an HMAC SHA-256 signature of the request body. Verify this signature using your configured Secret Key to ensure authenticity.

const crypto = require('crypto');

function verifyWebhookSignature(body, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(body, 'utf8')
    .digest('hex');
  
  return signature === expectedSignature;
}

​
Webhook Payloads

All webhook payloads include base execution data plus event-specific information:

Base Payload Structure
{
  "event": "event_type",
  "agent_execution": {
    "id": "exec_123abc",
    "started_at": "2024-01-01T12:00:00Z",
    "ended_at": "2024-01-01T12:05:00Z", // null if still running
    "status": "completed", // started, completed, failed, handoff
    "agent_id": "agent_456def"
  },
  "agent": {
    "id": "agent_456def",
    "name": "Customer Support Agent"
  }
}
Event-Specific Data

Handoff Event includes handoff details:

{
  "event": "agent_execution_handoff",
  // ... base payload ...
  "handoff": {
    "node_name": "Escalate to Human",
    "handoff_datetime": "2024-01-01T12:04:30Z",
    "handoff_reason": "Customer requested to speak with a human"
  }
}

Failed Event includes error information:

{
  "event": "agent_execution_failed",
  // ... base payload ...
  "failure": {
    "error": {
      "message": "Failed to connect to external API",
      "type": "ConnectionError"
    },
    "failed_at": "2024-01-01T12:03:15Z"
  }
}

​
Webhook Best Practices

Important considerations:

  • Respond quickly (within 5 seconds) with a 2xx status code
  • Process webhook data asynchronously if needed