API & Webhooks - Kapso Documentation

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.

WhatsApp Webhooks

Kapso provides real-time webhooks for WhatsApp messaging events, enabling you to build powerful integrations and automate workflows based on WhatsApp conversations.

Configuring WhatsApp Webhooks

Navigate to your WhatsApp configuration settings
Go to the “Webhooks” tab
Click “Add Webhook” to create a new webhook endpoint
Configure the following:
- URL: Your endpoint that will receive webhook notifications
- Events: Select which events you want to subscribe to
- Secret Key: Auto-generated or provide your own (used for HMAC signature verification)
- Custom Headers: Optional additional headers for authentication

WhatsApp Webhook Events

Message Received

whatsapp.message.receivedFired when a new WhatsApp message is received from a customer. Supports message buffering for batch delivery.

Message Sent

whatsapp.message.sentFired when a message is successfully sent to WhatsApp

Message Delivered

whatsapp.message.deliveredFired when a message is successfully delivered to the recipient’s device

Message Read

whatsapp.message.readFired when the recipient reads your message

Message Failed

whatsapp.message.failedFired when a message fails to deliver

Conversation Created

whatsapp.conversation.createdFired when a new WhatsApp conversation is initiated

Conversation Ended

whatsapp.conversation.endedFired when a WhatsApp conversation ends (agent action, manual closure, or 24-hour inactivity)

Conversation Inactive

whatsapp.conversation.inactiveFired when no messages (inbound/outbound) for configured minutes (1-1440, default 60)

WhatsApp Webhook Headers

Every WhatsApp webhook request includes these headers:

X-Webhook-Event: whatsapp.message.received
X-Webhook-Signature: <hmac-hex-signature>
X-Idempotency-Key: <unique-key-per-event>
Content-Type: application/json

For batched message deliveries, additional headers are included:

X-Webhook-Batch: true
X-Batch-Size: <number-of-messages>

WhatsApp Webhook Payloads

Message Event Payload

For message-related events (received, sent, delivered, read, failed):

{
  "message": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "message_type": "text",
    "content": "Hello, I need help with my order",
    "direction": "inbound",
    "status": "received",
    "processing_status": "pending",
    "whatsapp_message_id": "wamid.HBgNNTU0MTIzNDU2Nzg5MA",
    "phone_number": "+1234567890",
    "has_media": false,
    "media_data": null,
    "message_type_data": {},
    "created_at": "2024-01-15T14:30:00Z",
    "updated_at": "2024-01-15T14:30:00Z"
  },
  "conversation": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "phone_number": "+1234567890",
    "status": "active",
    "last_active_at": "2024-01-15T14:30:00Z",
    "whatsapp_config_id": "770e8400-e29b-41d4-a716-446655440002",
    "metadata": {},
    "created_at": "2024-01-15T14:00:00Z",
    "updated_at": "2024-01-15T14:30:00Z"
  },
  "is_new_conversation": false,
  "whatsapp_config": {
    "id": "770e8400-e29b-41d4-a716-446655440002",
    "name": "Production WhatsApp",
    "phone_number_id": "123456789012345",
    "business_account_id": "987654321098765",
    "is_coexistence": false,
    "webhook_verified_at": "2024-01-10T08:00:00Z",
    "created_at": "2024-01-10T08:00:00Z",
    "updated_at": "2024-01-15T14:30:00Z",
    "customer_id": "880e8400-e29b-41d4-a716-446655440003",
    "display_name": "Production WhatsApp",
    "display_phone_number": "+1 (555) 123-4567",
    "display_phone_number_normalized": "15551234567"
  }
}

Conversation Created/Ended Payload

For the whatsapp.conversation.created and whatsapp.conversation.ended events:

{
  "conversation": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "phone_number": "+1234567890",
    "status": "active", // "ended" for conversation.ended events
    "last_active_at": "2024-01-15T14:30:00Z",
    "whatsapp_config_id": "770e8400-e29b-41d4-a716-446655440002",
    "metadata": {},
    "created_at": "2024-01-15T14:30:00Z",
    "updated_at": "2024-01-15T14:30:00Z"
  },
  "whatsapp_config": {
    "id": "770e8400-e29b-41d4-a716-446655440002",
    "name": "Production WhatsApp",
    "phone_number_id": "123456789012345",
    "business_account_id": "987654321098765",
    "is_coexistence": false,
    "webhook_verified_at": "2024-01-10T08:00:00Z",
    "created_at": "2024-01-10T08:00:00Z",
    "updated_at": "2024-01-15T14:30:00Z",
    "customer_id": "880e8400-e29b-41d4-a716-446655440003",
    "display_name": "Production WhatsApp",
    "display_phone_number": "+1 (555) 123-4567",
    "display_phone_number_normalized": "15551234567"
  }
}

For whatsapp.conversation.ended events, the conversation status will be “ended”. This event is triggered when:

An agent ends the conversation through an action
A human manually closes the conversation
The conversation automatically ends after 24 hours of inactivity

The last_active_at timestamp indicates when the conversation was last active.

Conversation Inactive Payload

For the whatsapp.conversation.inactive event:

{
  "conversation": {
    "id": "4d7e8400-e29b-41d4-a716-446655440001",
    "phone_number": "+15551234567",
    "status": "active",
    "last_active_at": "2025-10-02T12:34:56Z",
    "created_at": "2024-01-15T10:00:00Z",
    "updated_at": "2025-10-02T12:34:56Z",
    "metadata": {},
    "whatsapp_config_id": "770e8400-e29b-41d4-a716-446655440002"
  },
  "whatsapp_config": {
    "id": "770e8400-e29b-41d4-a716-446655440002",
    "name": "Main Line",
    "phone_number_id": "123456789012345",
    "business_account_id": "987654321098765",
    "is_coexistence": false,
    "webhook_verified_at": "2024-01-10T08:00:00Z",
    "created_at": "2024-01-10T08:00:00Z",
    "updated_at": "2024-01-15T10:00:00Z",
    "customer_id": "880e8400-e29b-41d4-a716-446655440003",
    "display_name": "Main Line",
    "display_phone_number": "+1 (555) 123-4567",
    "display_phone_number_normalized": "15551234567"
  },
  "since_message": {
    "id": "f2ab8400-e29b-41d4-a716-446655440003",
    "whatsapp_message_id": "wamid.HBgNNTU0MTIzNDU2Nzg5MA",
    "direction": "inbound",
    "created_at": "2025-10-02T11:34:56Z"
  },
  "inactivity": {
    "minutes": 45
  }
}

For whatsapp.conversation.inactive events:

since_message contains the last message in the conversation (inbound or outbound)
direction indicates whether the last message was from customer (“inbound”) or you (“outbound”)
inactivity.minutes shows your configured threshold
Calculate deadline: since_message.created_at + inactivity.minutes
Idempotency key is SHA-256 hash of webhook ID + message ID
Any new message before the timer fires cancels the event automatically
Won’t fire for ended conversations or historical imports

Message Types

The message_type field can be one of:

text - Plain text message
image - Image attachment
video - Video attachment
audio - Audio/voice message
document - Document attachment
location - Location sharing
template - WhatsApp template message
interactive - Interactive message (buttons, lists)
reaction - Message reaction
contacts - Contact card sharing

Message Type-Specific Data

The message_type_data field contains different information based on the message type:

Media Messages (image/video/document/audio)

{
  "message_type": "image",
  "message_type_data": {
    "caption": "Photo description",
    "has_media": true
  },
  "media_data": {
    "url": "https://app.kapso.ai/rails/active_storage/blobs/...",
    "filename": "photo.jpg",
    "content_type": "image/jpeg",
    "byte_size": 204800
  }
}

Location Messages

{
  "message_type": "location",
  "message_type_data": {
    "latitude": 37.7749,
    "longitude": -122.4194,
    "name": "San Francisco",
    "address": "San Francisco, CA, USA"
  }
}

Template Messages

{
  "message_type": "template",
  "message_type_data": {
    "name": "order_confirmation",
    "language": "en_US",
    "params": ["John", "12345", "$99.99"]
  }
}

Interactive Messages

{
  "message_type": "interactive",
  "message_type_data": {
    "type": "button",
    "body_text": "Please select an option",
    "header_text": "Quick Actions",
    "footer_text": "Choose one"
  }
}

Reaction Messages

{
  "message_type": "reaction",
  "message_type_data": {
    "emoji": "👍",
    "message_id": "wamid.HBgNNTU0MTIzNDU2Nzg5MA"
  }
}

WhatsApp Message Buffering

Message buffering allows you to receive multiple whatsapp.message.received events in a single batched webhook, reducing the load on your servers during high-volume conversations.

How It Works

Debounce Pattern: Messages are collected in a buffer until the configured time window expires without receiving new messages
Automatic Batching: Multiple messages from the same conversation are grouped together
Immediate Delivery: Batches are sent when the maximum batch size is reached or the buffer window expires
Per-Conversation Buffering: Each conversation has its own independent buffer

Configuration

When creating or editing a webhook, enable message buffering for the whatsapp.message.received event:

Buffer Window: Time to wait before sending batched messages (1-60 seconds, default: 5)
Maximum Batch Size: Maximum messages per batch (1-100, default: 50)

Batched Webhook Format

When messages are buffered, your endpoint receives the same whatsapp.message.received event type with an array of messages:

{
  "type": "whatsapp.message.received",
  "batch": true,
  "data": [
    {
      "message": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "message_type": "text",
        "content": "First message",
        // ... full message object
      },
      "conversation": {
        // ... conversation object
      },
      "is_new_conversation": false,
      "whatsapp_config": {
        // ... config object
      }
    },
    {
      "message": {
        "id": "660e8400-e29b-41d4-a716-446655440001",
        "message_type": "text",
        "content": "Second message",
        // ... full message object
      },
      "conversation": {
        // ... conversation object
      },
      "is_new_conversation": false,
      "whatsapp_config": {
        // ... config object
      }
    }
  ],
  "batch_info": {
    "size": 2,
    "window_ms": 5000,
    "first_sequence": 1,
    "last_sequence": 2,
    "conversation_id": "770e8400-e29b-41d4-a716-446655440002"
  }
}

Important: When buffering is enabled, ALL messages are delivered in the batch format, even single messages. The data array will contain just one message if only one message was received during the buffer window. Always check the batch field or X-Webhook-Batch header to determine if you’re receiving a batched delivery.

Verifying WhatsApp Webhooks

Always verify the webhook signature to ensure the request is authentic:

const crypto = require('crypto');

app.post('/webhook/whatsapp', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const body = JSON.stringify(req.body);
  
  // Your webhook's secret key
  const secret = process.env.WHATSAPP_WEBHOOK_SECRET;
  
  // Calculate expected signature
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(body, 'utf8')
    .digest('hex');
  
  if (signature !== expectedSignature) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process the webhook
  const event = req.headers['x-webhook-event'];
  const idempotencyKey = req.headers['x-idempotency-key'];
  
  // Handle the event...
  
  res.status(200).send('OK');
});

Testing WhatsApp Webhooks

You can test your webhook endpoints directly from the Kapso interface:

Go to your WhatsApp webhook configuration
Click the “Test Webhook” button
Select an event type to test
Review the sample payload that will be sent
Click “Send Test” to trigger a test webhook

The test will use realistic sample data that matches the exact structure of production webhooks.

Webhook Reliability

Kapso implements several features to ensure reliable webhook delivery:

Retries: Failed webhooks are retried up to 3 times with fast exponential backoff (10 seconds, 40 seconds, 90 seconds)
Total Time to Failure: Approximately 2.5 minutes from first attempt to final failure
Timeout: Webhook requests timeout after 30 seconds (45 seconds for batched deliveries)
Idempotency: Each event has a unique idempotency key to prevent duplicate processing
Delivery Tracking: All webhook deliveries are logged with full request/response details
Message Ordering: WhatsApp message webhooks are delivered in sequence order within conversations to maintain message chronology
Batch Consistency: When buffering is enabled, messages are always delivered in batch format, even during retries. After max retries, the batch is marked as permanently failed.

WhatsApp Message Ordering

Kapso ensures WhatsApp messages are delivered to your webhooks in the correct order within each conversation:

Sequence-based Ordering: Each webhook delivery within a conversation is assigned a sequence number
Automatic Queuing: Messages are automatically queued if earlier messages haven’t been delivered yet
Ordering Timeout: After 30 seconds, messages are delivered regardless of ordering to prevent indefinite delays
Applies To: Message received (whatsapp.message.received) and message sent (whatsapp.message.sent) events
Per Conversation: Ordering is maintained within each conversation independently

This ensures your webhook endpoint receives messages in the same order they were sent/received, making it easier to maintain conversation context and state.

Best Practices for WhatsApp Webhooks

Handle Events Asynchronously: Process webhook data in background jobs to respond quickly
Implement Idempotency: Use the X-Idempotency-Key header to prevent processing duplicates
Monitor Failures: Set up alerts for webhook delivery failures
Secure Your Endpoint: Always verify signatures and use HTTPS
Handle All Event Types: Even if you only need certain events now, handle all types gracefully
Process Quickly: Respond within 5 seconds to avoid being marked as failed delivery

Project Webhooks

Project-level webhooks notify you about project-wide events like customer onboarding.

Configuring Project Webhooks

Configure project webhooks in the Kapso web app:

Open the sidebar and click Webhooks
Go to the Project webhooks tab
Click Add Webhook
Enter your HTTPS endpoint URL
Copy the auto-generated secret key for signature verification

Your endpoint must:

Accept POST requests
Return 200 status within 10 seconds
Handle duplicate events (idempotent)

Project Webhook Events

WhatsApp Config Created

whatsapp.config.createdFired when a customer successfully connects their WhatsApp through a setup link

Project Webhook Headers

Every project webhook request includes:

X-Webhook-Event: whatsapp.config.created
X-Webhook-Signature: <hmac-hex-signature>
X-Idempotency-Key: <unique-key-per-event>
Content-Type: application/json

Project Webhook Payloads

WhatsApp Config Created Payload

For the whatsapp.config.created event:

{
  "whatsapp_config": {
    "id": "770e8400-e29b-41d4-a716-446655440002",
    "name": "Production WhatsApp",
    "phone_number_id": "123456789012345",
    "business_account_id": "987654321098765",
    "is_coexistence": false,
    "inbound_processing_enabled": true,
    "calls_enabled": false,
    "webhook_verified_at": "2024-01-10T08:00:00Z",
    "created_at": "2024-01-10T08:00:00Z",
    "updated_at": "2024-01-15T14:30:00Z",
    "customer_id": "880e8400-e29b-41d4-a716-446655440003",
    "display_name": "Production WhatsApp",
    "display_phone_number": "+1 (555) 123-4567",
    "display_phone_number_normalized": "15551234567"
  },
  "project": {
    "id": "990e8400-e29b-41d4-a716-446655440004",
    "name": "My SaaS Platform",
    "description": "Customer communications platform",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-15T14:30:00Z"
  },
  "customer": {
    "id": "880e8400-e29b-41d4-a716-446655440003",
    "name": "Acme Corporation",
    "external_customer_id": "acme-corp-123",
    "created_at": "2024-01-08T10:00:00Z",
    "updated_at": "2024-01-15T14:30:00Z"
  },
  "setup_link": {
    "id": "aa0e8400-e29b-41d4-a716-446655440005",
    "status": "used",
    "created_at": "2024-01-15T14:00:00Z",
    "expires_at": "2024-02-14T14:00:00Z",
    "success_redirect_url": "https://your-app.com/onboarding/success",
    "failure_redirect_url": "https://your-app.com/onboarding/error",
    "allowed_connection_types": ["coexistence", "dedicated"],
    "theme_config": null,
    "provision_phone_number": false,
    "phone_number_area_code": null,
    "phone_number_country_isos": ["US"],
    "whatsapp_setup_status": "completed",
    "whatsapp_setup_error": null,
    "url": "https://setup.kapso.ai/s/abc123"
  },
  "phone_number": {
    "id": "bb0e8400-e29b-41d4-a716-446655440006",
    "phone_number": "+15551234567",
    "status": "active",
    "area_code": "555",
    "country_iso": "US",
    "country_dial_code": "1",
    "provisioned_at": "2024-01-15T14:25:00Z",
    "released_at": null,
    "display_number": "+1 (555) 123-4567"
  },
  "creation_context": {
    "sandbox": false,
    "coexistence": false
  }
}

The whatsapp.config.created event provides complete context about:

The WhatsApp configuration that was created
The project and customer it belongs to
The setup link that was used (if any)
The phone number associated with the config
Whether it’s a sandbox or coexistence setup

Use this event to:

Update your database when customers complete onboarding
Trigger welcome messages or onboarding flows
Track customer activation metrics
Sync WhatsApp connection status with your systems

Verifying Project Webhooks

Project webhooks use the same HMAC SHA-256 signature verification as WhatsApp webhooks. See Verifying WhatsApp Webhooks above for examples.

Project Webhook Reliability

Project webhooks use the same reliability features as WhatsApp webhooks:

Retries: Failed webhooks are retried up to 3 times with fast exponential backoff (10s, 40s, 90s)
Total Time to Failure: Approximately 2.5 minutes from first attempt to final failure
Timeout: Webhook requests timeout after 30 seconds
Idempotency: Each event has a unique idempotency key to prevent duplicate processing
Delivery Tracking: All webhook deliveries are logged with full request/response 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 your agents to send real-time notifications to your systems when important events occur during execution.

Configuration

Navigate to your agent’s “API & Webhooks” settings
Add webhook endpoints for the events you want to monitor
Configure a Secret Key for request verification
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"
  }
}

Webhook 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

Getting started

Guides

API Reference

Customers

WhatsApp Display Names

Setup Links

WhatsApp Webhooks

WhatsApp Configs

WhatsApp Broadcasts

​Authentication

​WhatsApp Webhooks

​Configuring WhatsApp Webhooks

​WhatsApp Webhook Events

Message Received

Message Sent

Message Delivered

Message Read

Message Failed

Conversation Created

Conversation Ended

Conversation Inactive

​WhatsApp Webhook Headers

​WhatsApp Webhook Payloads

​Message Event Payload

​Conversation Created/Ended Payload

​Conversation Inactive Payload

​Message Types

​Message Type-Specific Data

​Media Messages (image/video/document/audio)

​Location Messages

​Template Messages

​Interactive Messages

​Reaction Messages

​WhatsApp Message Buffering

​How It Works

​Configuration

​Batched Webhook Format

​Verifying WhatsApp Webhooks

​Testing WhatsApp Webhooks

​Webhook Reliability

​WhatsApp Message Ordering

​Best Practices for WhatsApp Webhooks

​Project Webhooks

​Configuring Project Webhooks

​Project Webhook Events

WhatsApp Config Created

​Project Webhook Headers

​Project Webhook Payloads

​WhatsApp Config Created Payload

​Verifying Project Webhooks

​Project Webhook Reliability

​Agent Webhooks

​Incoming Webhooks (Triggering Agents)

​Outbound Webhooks (Agent Notifications)

​Configuration

​Supported Events

Execution Started

Execution Ended

Execution Failed

Handoff Required

​Security & Verification

​Webhook Payloads

Base Payload Structure

Event-Specific Data

​Webhook Best Practices

Authentication

WhatsApp Webhooks

Configuring WhatsApp Webhooks

WhatsApp Webhook Events

WhatsApp Webhook Headers

WhatsApp Webhook Payloads

Message Event Payload

Conversation Created/Ended Payload

Conversation Inactive Payload

Message Types

Message Type-Specific Data

Media Messages (image/video/document/audio)

Location Messages

Template Messages

Interactive Messages

Reaction Messages

WhatsApp Message Buffering

How It Works

Configuration

Batched Webhook Format

Verifying WhatsApp Webhooks

Testing WhatsApp Webhooks

Webhook Reliability

WhatsApp Message Ordering

Best Practices for WhatsApp Webhooks

Project Webhooks

Configuring Project Webhooks

Project Webhook Events

Project Webhook Headers

Project Webhook Payloads

WhatsApp Config Created Payload

Verifying Project Webhooks

Project Webhook Reliability

Agent Webhooks

Incoming Webhooks (Triggering Agents)

Outbound Webhooks (Agent Notifications)

Configuration

Supported Events

Security & Verification

Webhook Payloads

Webhook Best Practices