Skip to main content
You have two ways to receive WhatsApp messages and events.

​
1. Kapso webhooks

Kapso sends structured webhook events when messages arrive, conversations change, or delivery status updates. Events include:
  • whatsapp.message.received - New message from customer
  • whatsapp.message.sent - Message sent to WhatsApp
  • whatsapp.message.delivered - Message delivered
  • whatsapp.message.read - Message read
  • whatsapp.conversation.created - New conversation
  • whatsapp.conversation.ended - Conversation ended
  • whatsapp.conversation.inactive - No activity for X minutes
Setup:
  1. Go to Webhooks documentation
  2. Configure webhook URL and events
  3. Receive structured JSON payloads

Full webhook documentation

Complete guide to webhook events, signatures, retries, and best practices.

​
2. Forward Meta webhooks

Alternatively, forward raw Meta webhooks directly to your server. This gives you the exact payload Meta sends, without Kapso’s processing layer. Setup:
  1. Go to your WhatsApp configuration in Kapso dashboard
  2. Click Edit on your connected number
  3. Add your Webhook destination URL
  4. We’ll forward all Meta webhook events to your endpoint

​
Parse forwarded webhooks

Use the TypeScript SDK to parse raw Meta webhooks: 
import express from 'express';
import { normalizeWebhook } from '@kapso/whatsapp-cloud-api/server';

const app = express();

app.post('/webhook', express.json(), (req, res) => {
  // Parse webhook
  const events = normalizeWebhook(req.body);

  // Handle messages
  events.messages.forEach((message) => {
    console.log(message.type, message.kapso?.direction);
  });

  // Handle other events
  events.raw.accountAlerts?.forEach((alert) => {
    console.log('Account alert', alert.alertInfo?.alertType);
  });

  res.sendStatus(200);
});
normalizeWebhook() converts Meta’s payload to the same structure as messages.query(), adds kapso.direction, and keeps all raw fields under events.raw.