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.

​
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

VariableRequiredDescription
WHATSAPP_WEBHOOK_VERIFY_TOKENYesToken for Meta webhook verification (GET requests)
WHATSAPP_APP_SECRETYesMeta 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
Handles delivery status callbacks from multiple providers. The endpoint automatically detects the payload format and normalizes it into a standard event structure.

​
Supported Providers

ProviderDetection MethodPayload Format
AWS SESnotificationType field or SNS Type: "Notification" wrapperSNS notification with nested JSON Message
SendGridArray payload with sg_message_id fieldArray of event objects
TwilioMessage-SID field on the form body (see example below)Form-style status callback
StandardproviderMessageId + event fieldsKaireonAI native format
You can also pass an X-Provider header (ses, sendgrid, twilio) to explicitly hint the format.

​
Twilio status-callback form body

Twilio sends delivery status as an application/x-www-form-urlencoded POST. The endpoint detects the format by the presence of the message-SID field (the preferred form) or its legacy alias. See the Twilio Message Status Values reference for the full list of status values. The exact wire-field names are shown in the example below: 
# Example status-callback POST that Twilio sends to your webhook URL
curl -X POST https://your-domain.kaireonai.com/api/v1/webhooks/delivery \
  -d "MessageSid=SM1234567890abcdef1234567890abcdef" \
  -d "SmsSid=SM1234567890abcdef1234567890abcdef" \
  -d "MessageStatus=delivered" \
  -d "To=%2B15005550006" \
  -d "From=%2B15005550001"

​
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>
The HMAC is computed over the raw request body using the 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:
EventDescription
deliveredMessage was delivered to the recipient
bouncedMessage bounced or was marked as spam
openedRecipient opened the message
clickedRecipient clicked a link
failedDelivery failed

​
Environment Variables

VariableRequiredDescription
WEBHOOK_SIGNING_SECRETYesShared secret for HMAC-SHA256 signature verification