Agent webhooks

Two-way communication between your systems and Kapso agents

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.

Node.js

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