Skip to main content

​
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
Query Parameters:
ParameterDescription
hub.modeMust be subscribe
hub.verify_tokenMust match your WHATSAPP_WEBHOOK_VERIFY_TOKEN env var
hub.challengeChallenge string to echo back
Response: Returns the 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
Payload (from Meta): 
{
  "object": "whatsapp_business_account",
  "entry": [{
    "changes": [{
      "value": {
        "statuses": [{
          "id": "wamid.ABCdef123",
          "status": "delivered",
          "timestamp": "1679000000"
        }]
      }
    }]
  }]
}
Status Mapping:
Meta StatusKaireonAI Status
sentdelivered
delivereddelivered
readopened
failedfailed
Response: Always returns 200 to acknowledge receipt.

​
Environment Variables

VariableRequiredDescription
WHATSAPP_WEBHOOK_VERIFY_TOKENYesToken for Meta webhook verification

​
Delivery Webhook

Generic webhook delivery for the webhook channel type. 
POST /api/v1/webhooks/delivery
Handles delivery status callbacks from custom webhook integrations. Updates delivery tracking records with provider-reported statuses.