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.

This page is about outgoing webhooks you configure to receive events from Kaanha AI. It’s unrelated to the many inbound webhooks Kaanha AI itself receives from providers (WhatsApp, Stripe, Shopify, Twilio, and others) to make the platform work — those aren’t something you configure.

Setting Up a Webhook

Go to Integrations → Webhooks → Add Webhook
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
Click Save. Use the Send test event action on the saved webhook to fire a test.ping event and confirm your endpoint is reachable — a webhook isn’t tested automatically just by saving it.

Event Types

Event	Trigger
`message.received`	Contact sends you a message
`message.status`	A message’s delivery status changes — delivered, read, or failed (check the `status` field in the payload to tell which)
`payment.completed`	Payment link paid
`csat.received`	A contact submits a CSAT rating

This is the complete event catalog today — if you need something else covered (e.g. contact-created, broadcast-completed), use an Automation Rule instead: automations can fire on many more triggers (contact/deal/order/pipeline events) and include a generic Webhook action, giving you a webhook call for events not in the list above.

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: `message.status`

{
  "event": "message.status",
  "organizationId": "clx...",
  "timestamp": "2026-03-24T10:30:05.000Z",
  "data": {
    "messageId": "wamid.xxx",
    "status": "read",
    "conversationId": "clx..."
  }
}

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-Webhook-Signature header:

X-Webhook-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-webhook-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 up to 3 times with a short backoff (roughly 1s, then 4s, then 16s) — all within the same delivery attempt, not spread out over minutes. A 4xx response is treated as a permanent rejection and is not retried at all, since it usually means something about the request itself needs fixing on your end, not a transient failure. After all retries are exhausted, the delivery is marked as failed and logged — there’s no later automatic redelivery for this feature, so if your endpoint is down for the whole retry window, that event is gone for good. (This is distinct from Automation Rules with a Webhook action, which fail into a separate retry queue and are periodically replayed — see the Automations DLQ banner if you’re using automation-triggered webhooks instead of this page’s IntegrationWebhook feature.)

Webhook Logs

View delivery history for each webhook in Integrations → Webhooks → [Name] → Logs:

Column	Description
Timestamp	When the delivery was attempted
Event	Event type
Status	`delivered` / `failed` / `pending`
Response Code	HTTP status from your server
Duration	Round-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.

Get Started

Messaging

AI & Automation

Analytics

Integrations

Platform

Webhooks

Webhooks

Setting Up a Webhook

Event Types

Payload Format

Example: `message.received`

Example: `message.status`

HMAC Signature Verification

Verification Example (Node.js)

Retry Policy

Webhook Logs

Zapier / Make / n8n Integration

​Webhooks

​Setting Up a Webhook

​Event Types

​Payload Format

​Example: message.received

​Example: message.status

​HMAC Signature Verification

​Verification Example (Node.js)

​Retry Policy

​Webhook Logs

​Zapier / Make / n8n Integration

Webhooks

Setting Up a Webhook

Event Types

Payload Format

Example: `message.received`

Example: `message.status`

HMAC Signature Verification

Verification Example (Node.js)

Retry Policy

Webhook Logs

Zapier / Make / n8n Integration