Set up webhooks - Kapso Documentation

This guide walks you through setting up webhooks for your WhatsApp configuration to receive real-time notifications when WhatsApp events occur.

Prerequisites

Before setting up webhooks, ensure you have:

A connected WhatsApp configuration in Kapso (or sandbox enabled)
An HTTP endpoint URL ready to receive webhook calls

Available webhook events

Kapso supports eight types of WhatsApp webhook events:

Message received

whatsapp.message.received - Triggered when a new message arrives from a customer

Message sent

whatsapp.message.sent - Triggered when a message is successfully sent to WhatsApp

Conversation created

whatsapp.conversation.created - Triggered when a new conversation begins

Conversation ended

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

Conversation inactive

whatsapp.conversation.inactive - Triggered when no messages (inbound/outbound) for configured minutes

Message delivered

whatsapp.message.delivered - Triggered when your message is delivered

Message read

whatsapp.message.read - Triggered when your message is read

Message failed

whatsapp.message.failed - Triggered when message delivery fails

Step 1: Navigate to webhook settings

Go to your WhatsApp configurations page
Click on the WhatsApp configuration you want to add webhooks to
Look for the Webhooks section or click Manage Webhooks

Step 2: Add a new webhook

Click the Add Webhook button to open the webhook configuration modal.

Step 3: Configure webhook settings

In the webhook configuration modal, you’ll need to provide:

Webhook URL

Enter the HTTPS endpoint URL where you want to receive webhook notifications. This must be a valid, publicly accessible URL.

Select events

Choose which events you want to receive notifications for. You can select one or multiple events:

Message received: Get notified for every incoming customer message
Message sent: Track when your messages are sent to WhatsApp
Conversation created: Know when new conversations start
Conversation ended: Be notified when conversations end (via agent action, manual closure, or 24-hour inactivity)
Conversation inactive: Triggered after no messages (inbound/outbound) for the configured time window
Message delivered: Track when your messages are delivered
Message read: Monitor when customers read your messages
Message failed: Be alerted when message delivery fails

Start with just the events you need. You can always add more events later by editing the webhook.

Message buffering (optional)

When you select the Message received event, you’ll see an option to enable message buffering. This feature helps reduce load on your webhook endpoint by batching multiple messages together.

Message buffering is only available for the whatsapp.message.received event.

How buffering works

When buffering is enabled:

Messages are collected in a buffer for a configurable time window
If multiple messages arrive within this window, they’re sent as a single batched webhook
The buffer uses a “debounce” pattern - each new message resets the timer
Messages are sent when the buffer window expires OR when the maximum batch size is reached

Buffer configuration options

Buffer Window: Time to wait before sending batched messages (1-60 seconds)
- Default: 5 seconds
- Example: With a 5-second window, messages keep accumulating until 5 seconds pass without a new message
Maximum Batch Size: Maximum number of messages in a single batch (1-100)
- Default: 50 messages
- The batch is sent immediately when this limit is reached

Batched webhook format

When messages are batched, your endpoint receives the same whatsapp.message.received event type, but with multiple messages:

{
  "type": "whatsapp.message.received",
  "batch": true,
  "data": [
    {
      // First message data
      "message": { ... },
      "conversation": { ... },
      "whatsapp_config": { ... }
    },
    {
      // Second message data
      "message": { ... },
      "conversation": { ... },
      "whatsapp_config": { ... }
    }
    // ... more messages
  ],
  "batch_info": {
    "size": 2,
    "window_ms": 5000,
    "first_sequence": 1,
    "last_sequence": 2,
    "conversation_id": "660e8400-e29b-41d4-a716-446655440001"
  }
}

Additional headers for batched webhooks:

X-Webhook-Batch: true - Indicates this is a batched delivery
X-Batch-Size: N - Number of messages in the batch

Single messages continue to use the original format. Your endpoint can check the batch field or X-Webhook-Batch header to determine if it’s receiving a batch.

Inactivity timeout (optional)

When you select the Conversation inactive event, configure the inactivity window:

Inactivity Minutes: Time to wait with no messages before triggering (1-1440 minutes)
- Default: 60 minutes (1 hour)
- Maximum: 1440 minutes (24 hours)
- Example: With 45 minutes, the webhook fires if no inbound or outbound messages for 45 minutes

Each new message resets the timer automatically. Historical imports and ended conversations don’t trigger this event.

Step 4: Save the webhook

Click Create Webhook to save your configuration. Kapso will:

Validate your webhook URL
Generate a unique secret key for webhook signature verification
Create the webhook in an active state

Step 5: View webhook details

After creation, you’ll see your webhook in the list with:

The webhook URL
Active events (with colored badges)
Secret key (hidden by default)
Last delivery status

Copying the secret key

The secret key is used to verify that webhook requests are coming from Kapso:

Click the eye icon to reveal the secret key
Click the copy icon to copy it to your clipboard
Store this key securely in your application

Keep your webhook secret key confidential. It’s used to generate signatures that verify webhook authenticity.

Step 6: Test your webhook

Before going live, test your webhook to ensure it’s working correctly:

Click the Test button next to your webhook
Select which event type you want to test
Click Send Test

Kapso will send a test payload to your webhook URL with:

Realistic sample data for the selected event
A test: true flag to identify it as a test
The same headers and signature as real webhooks

Webhook request format

Your endpoint will receive HTTP POST requests with:

Headers

Content-Type: application/json
X-Webhook-Event: whatsapp.message.received
X-Webhook-Signature: abc123...
X-Idempotency-Key: unique-event-key

Payload structure

For message events (received/sent/delivered/read/failed):

{
  "message": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "message_type": "text",
    "content": "Hello!",
    "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-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  },
  "conversation": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "phone_number": "+1234567890",
    "status": "active",
    "last_active_at": "2024-01-15T10:30:00Z",
    "whatsapp_config_id": "770e8400-e29b-41d4-a716-446655440002",
    "metadata": {},
    "created_at": "2024-01-15T10:00:00Z",
    "updated_at": "2024-01-15T10: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-15T10: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 conversation created/ended events:

{
  "conversation": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "phone_number": "+1234567890",
    "status": "active", // "ended" for conversation.ended events
    "last_active_at": "2024-01-15T10:00:00Z",
    "whatsapp_config_id": "770e8400-e29b-41d4-a716-446655440002",
    "metadata": {},
    "created_at": "2024-01-15T10:00:00Z",
    "updated_at": "2024-01-15T10:00: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-15T10:00: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 conversation inactive events:

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

Message type-specific data

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

Media messages (image/video/document):

{
  "message_type": "image",
  "message_type_data": {
    "caption": "Check out this photo!",
    "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"
  }
}

Verifying webhook signatures

To ensure webhook security, verify the signature in every request:

Extract the signature from the X-Webhook-Signature header
Compute the expected signature using HMAC-SHA256
Compare the signatures using a constant-time comparison

Example in Node.js:

const crypto = require('crypto');

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

Example in Ruby:

require 'openssl'

def verify_webhook_signature(payload, signature, secret)
  expected_signature = OpenSSL::HMAC.hexdigest('SHA256', secret, payload)
  
  # Use secure comparison to prevent timing attacks
  ActiveSupport::SecurityUtils.secure_compare(signature, expected_signature)
end

Managing webhooks

Editing webhooks

To modify a webhook:

Click the Edit button next to the webhook
Update the URL or events as needed
Toggle the active status if you want to pause the webhook
Click Update Webhook

Deactivating webhooks

You can temporarily disable a webhook without deleting it:

Click Edit on the webhook
Toggle off the Active switch
Click Update Webhook

The webhook will remain in your list but won’t receive any events.

Deleting webhooks

To permanently remove a webhook:

Click the Delete button (trash icon)
Confirm the deletion

Deleting a webhook is permanent and cannot be undone. Consider deactivating it instead if you might need it later.

Webhook delivery and retries

Kapso implements reliable webhook delivery:

Timeouts: Webhooks timeout after 30 seconds
Retries: Failed deliveries 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
Idempotency: Each event has a unique key to prevent duplicate processing
Status tracking: View the last delivery status for each webhook
Message Ordering: WhatsApp message webhooks are delivered in sequence order within conversations to maintain message chronology

Best practices

Use HTTPS endpoints

Always use secure HTTPS endpoints for webhooks. This ensures data is encrypted in transit.

Implement idempotency

Use the X-Idempotency-Key header to ensure you process each event only once, even if it’s delivered multiple times.

Respond quickly

Return a 2xx status code within 5 seconds to avoid being marked as failed. Process webhook data asynchronously if needed.

Verify signatures

Always verify webhook signatures to ensure requests are authentic and haven’t been tampered with.

Handle errors gracefully

Implement proper error handling and logging to diagnose issues with webhook processing.

Troubleshooting

Webhook not receiving events

If your webhook isn’t receiving events:

Check that the webhook is active (not deactivated)
Verify the URL is correct and publicly accessible
Ensure your endpoint returns a 2xx status code
Check if there’s a firewall blocking Kapso’s requests
Test the webhook using the test feature

Signature verification failing

If signature verification fails:

Ensure you’re using the exact payload body (raw request body)
Verify you’re using the correct secret key
Check that you’re implementing HMAC-SHA256 correctly
Make sure you’re not adding any prefix like “sha256=” - Kapso sends the raw hex digest

Missing events

If you’re not receiving expected events:

Verify the correct events are selected in your webhook configuration
Check that the WhatsApp configuration is active
Ensure your endpoint is responding with 2xx status codes
Review the webhook’s last delivery status for errors

Next steps

Now that your webhooks are configured, you can:

Build automation workflows based on incoming messages
Integrate with your CRM or support system
Track message delivery and read receipts
Monitor conversation patterns and metrics

For more advanced webhook usage and API integration, see our API documentation.

Overview

Tools & SDKs

API Reference

WhatsApp Conversations

WhatsApp Messages

Conversation Assignments

WhatsApp Templates

WhatsApp Contacts

WhatsApp Contact Notes

WhatsApp Configs

WhatsApp Calls

WhatsApp Contact Call Permissions

​Prerequisites

​Available webhook events

Message received

Message sent

Conversation created

Conversation ended

Conversation inactive

Message delivered

Message read

Message failed

​Step 1: Navigate to webhook settings

​Step 2: Add a new webhook

​Step 3: Configure webhook settings

​Webhook URL

​Select events

​Message buffering (optional)

​How buffering works

​Buffer configuration options

​Batched webhook format

​Inactivity timeout (optional)

​Step 4: Save the webhook

​Step 5: View webhook details

​Copying the secret key

​Step 6: Test your webhook

​Webhook request format

​Headers

​Payload structure

​Message type-specific data

​Media messages (image/video/document):

​Location messages:

​Template messages:

​Interactive messages:

​Reaction messages:

​Verifying webhook signatures

​Managing webhooks

​Editing webhooks

​Deactivating webhooks

​Deleting webhooks

​Webhook delivery and retries

​Best practices

​Troubleshooting

​Webhook not receiving events

​Signature verification failing

​Missing events

​Next steps

Prerequisites

Available webhook events

Step 1: Navigate to webhook settings

Step 2: Add a new webhook

Step 3: Configure webhook settings

Webhook URL

Select events

Message buffering (optional)

How buffering works

Buffer configuration options

Batched webhook format

Inactivity timeout (optional)

Step 4: Save the webhook

Step 5: View webhook details

Copying the secret key

Step 6: Test your webhook

Webhook request format

Headers

Payload structure

Message type-specific data

Media messages (image/video/document):

Location messages:

Template messages:

Interactive messages:

Reaction messages:

Verifying webhook signatures

Managing webhooks

Editing webhooks

Deactivating webhooks

Deleting webhooks

Webhook delivery and retries

Best practices

Troubleshooting

Webhook not receiving events

Signature verification failing

Missing events

Next steps