Skip to main content
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_startedFired when an agent begins processing

Execution ended

agent_execution_endedFired when an agent completes successfully

Execution failed

agent_execution_failedFired when an agent encounters an error

Handoff required

agent_execution_handoffFired 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"
  }
}

​
Best practices

Important considerations:
  • Respond quickly (within 5 seconds) with a 2xx status code
  • Process webhook data asynchronously if needed
  • Store the webhook secret securely
  • Always verify webhook signatures
  • Implement idempotency handling using the provided idempotency key