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 five types of WhatsApp webhook events:

​

Step 1: Navigate to webhook settings

1. Go to your WhatsApp configurations page
2. Click on the WhatsApp configuration you want to add webhooks to
3. 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
• Conversation created: Know when new conversations start
• Message delivered: Track when your messages are delivered
• Message read: Monitor when customers read your messages
• Message failed: Be alerted when message delivery fails

​

Step 4: Save the webhook

Click Create Webhook to save your configuration. Kapso will:

1. Validate your webhook URL
2. Generate a unique secret key for webhook signature verification
3. 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:

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

​

Step 6: Test your webhook

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

1. Click the Test button next to your webhook
2. Select which event type you want to test
3. 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: sha256=abc123...
X-Idempotency-Key: unique-event-key

​

Payload structure

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

{
  "message": {
    "id": "uuid",
    "message_type": "text",
    "content": "Hello!",
    "direction": "inbound",
    "status": "received",
    "phone_number": "+1234567890",
    "created_at": "2024-01-15T10:30:00Z",
    "metadata": {}
  },
  "conversation": {
    "id": "uuid",
    "phone_number": "+1234567890",
    "status": "active",
    "created_at": "2024-01-15T10:00:00Z"
  },
  "is_new_conversation": false
}

​

Verifying webhook signatures

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

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

Example in Node.js:

const crypto = require('crypto');

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

​

Managing webhooks

​

Editing webhooks

To modify a webhook:

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

​

Deactivating webhooks

You can temporarily disable a webhook without deleting it:

1. Click Edit on the webhook
2. Toggle off the Active switch
3. Click Update Webhook

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

​

Deleting webhooks

To permanently remove a webhook:

1. Click the Delete button (trash icon)
2. Confirm the deletion

​

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 exponential backoff (1 min, 4 min, 9 min)
• Idempotency: Each event has a unique key to prevent duplicate processing
• Status tracking: View the last delivery status for each webhook

​

Best practices

​

Troubleshooting

​

Webhook not receiving events

If your webhook isn’t receiving events:

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

​

Signature verification failing

If signature verification fails:

1. Ensure you’re using the exact payload body (raw request body)
2. Verify you’re using the correct secret key
3. Check that you’re implementing HMAC-SHA256 correctly
4. Make sure you’re comparing the full header value (including “sha256=” prefix)

​

Missing events

If you’re not receiving expected events:

1. Verify the correct events are selected in your webhook configuration
2. Check that the WhatsApp configuration is active
3. Ensure your endpoint is responding with 2xx status codes
4. 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.