Skip to main content

​
Webhooks

Kaanha AI can send real-time event notifications to your server via outgoing webhooks. This allows you to integrate with any backend system, CRM, or automation tool.

​
Setting Up a Webhook

  1. Go to Integrations → Webhooks → Add Webhook
  2. Enter:
    • Name: Descriptive label (e.g., “CRM Sync”)
    • URL: Your server endpoint (must be HTTPS, publicly accessible)
    • Events: Select which events to subscribe to
    • Secret: Optional — used for HMAC signature verification
  3. Click Save. Kaanha AI will immediately send a test event.

​
Event Types

EventTrigger
message.receivedContact sends you a message
message.sentYou send a message
message.deliveredMessage delivered to device
message.readMessage read by contact
conversation.openedNew conversation created
conversation.resolvedConversation marked resolved
contact.createdNew contact added
contact.updatedContact profile updated
contact.opted_outContact sent STOP / unsubscribed
broadcast.completedBroadcast finishes sending
payment.completedPayment link paid

​
Payload Format

All events are delivered as POST requests with Content-Type: application/json.

​
Example: message.received

{
  "event": "message.received",
  "organizationId": "clx...",
  "timestamp": "2026-03-24T10:30:00.000Z",
  "data": {
    "messageId": "wamid.xxx",
    "conversationId": "clx...",
    "contact": {
      "id": "clx...",
      "phone": "+919876543210",
      "name": "John Doe",
      "tags": ["vip"]
    },
    "message": {
      "type": "text",
      "text": "Hi, I need help with my order",
      "timestamp": "2026-03-24T10:29:58.000Z"
    }
  }
}

​
Example: contact.created

{
  "event": "contact.created",
  "organizationId": "clx...",
  "timestamp": "2026-03-24T10:30:00.000Z",
  "data": {
    "contact": {
      "id": "clx...",
      "phone": "+919876543210",
      "name": "Jane Smith",
      "email": "jane@example.com",
      "tags": [],
      "optedIn": true,
      "createdAt": "2026-03-24T10:30:00.000Z"
    }
  }
}

​
HMAC Signature Verification

If you set a Secret on your webhook, Kaanha AI signs every request with HMAC-SHA256. The signature is sent in the X-Kaanha-Signature header: 
X-Kaanha-Signature: sha256=abc123...

​
Verification Example (Node.js)

const crypto = require('crypto');

function verifyWebhook(rawBody, signature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// Express middleware
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = req.headers['x-kaanha-signature'];
  if (!verifyWebhook(req.body, sig, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(req.body);
  console.log('Event:', event.event);
  res.status(200).send('OK');
});

​
Retry Policy

If your server returns a non-2xx response, Kaanha AI retries with exponential backoff:
AttemptDelay
1st retry5 seconds
2nd retry25 seconds
3rd retry2 minutes
After 3 failed attempts, the delivery is marked as failed and logged.

​
Webhook Logs

View delivery history for each webhook in Integrations → Webhooks → [Name] → Logs:
ColumnDescription
TimestampWhen the delivery was attempted
EventEvent type
Statusdelivered / failed / pending
Response CodeHTTP status from your server
DurationRound-trip time in ms

​
Zapier / Make / n8n Integration

Kaanha AI supports direct integration with no-code automation platforms. Discovery endpoint (for custom apps): 
GET https://app.kaanha.ai/api/integrations/describe
Authorization: Bearer YOUR_API_KEY
Returns all available triggers and actions for platform discovery. For Zapier: use the Webhooks by Zapier trigger with your Kaanha AI webhook URL. For Make (Integromat): use the Webhooks module.