Documentation Index
Fetch the complete documentation index at: https://docs.kaireonai.com/llms.txt
Use this file to discover all available pages before exploring further.
WhatsApp Webhook
Receives delivery status callbacks from the Meta WhatsApp Cloud API.
Verification (GET)
Meta requires webhook verification during setup. When you configure the webhook URL in the Meta Developer Dashboard, Meta sends a verification request.
GET /api/v1/webhooks/whatsapp?hub.mode=subscribe&hub.verify_token=YOUR_TOKEN&hub.challenge=CHALLENGE
| Parameter | Description |
|---|
hub.mode | Must be subscribe |
hub.verify_token | Must match your WHATSAPP_WEBHOOK_VERIFY_TOKEN env var |
hub.challenge | Challenge string to echo back |
hub.challenge value as plain text (200) if token matches, or 403 if verification fails.
Status Callbacks (POST)
Meta sends delivery status updates as POST requests when message statuses change.
POST /api/v1/webhooks/whatsapp
{
"object": "whatsapp_business_account",
"entry": [{
"changes": [{
"value": {
"statuses": [{
"id": "wamid.ABCdef123",
"status": "delivered",
"timestamp": "1679000000"
}]
}
}]
}]
}
| Meta Status | KaireonAI Status |
|---|
sent | delivered |
delivered | delivered |
read | opened |
failed | failed |
Signature Verification
WhatsApp webhooks are verified using HMAC-SHA256 signature verification. Meta signs every POST payload with your app secret and includes the signature in the x-hub-signature-256 header.
The platform computes the expected signature using the WHATSAPP_APP_SECRET environment variable and compares it to the header value using crypto.timingSafeEqual to prevent timing attacks. Requests with missing or invalid signatures are rejected with 401.
Environment Variables
| Variable | Required | Description |
|---|
WHATSAPP_WEBHOOK_VERIFY_TOKEN | Yes | Token for Meta webhook verification (GET requests) |
WHATSAPP_APP_SECRET | Yes | Meta app secret for HMAC-SHA256 signature verification (POST requests) |
Delivery Webhook
Universal delivery status webhook that auto-detects provider payload formats.
POST /api/v1/webhooks/delivery
Supported Providers
| Provider | Detection Method | Payload Format |
|---|
| AWS SES | notificationType field or SNS Type: "Notification" wrapper | SNS notification with nested JSON Message |
| SendGrid | Array payload with sg_message_id field | Array of event objects |
| Twilio | MessageSid or SmsSid field | Form-style status callback |
| Standard | providerMessageId + event fields | KaireonAI native format |
X-Provider header (ses, sendgrid, twilio) to explicitly hint the format.
Signature Verification
Delivery webhooks are verified using HMAC-SHA256 signature verification. Include the signature in the X-Webhook-Signature header:
X-Webhook-Signature: sha256=<hex-encoded-hmac>
WEBHOOK_SIGNING_SECRET environment variable. Requests with missing or invalid signatures are rejected with 401.
Normalized Events
All provider payloads are normalized to a standard event:
| Event | Description |
|---|
delivered | Message was delivered to the recipient |
bounced | Message bounced or was marked as spam |
opened | Recipient opened the message |
clicked | Recipient clicked a link |
failed | Delivery failed |
Environment Variables
| Variable | Required | Description |
|---|
WEBHOOK_SIGNING_SECRET | Yes | Shared secret for HMAC-SHA256 signature verification |
