Webhooks Overview

Webhooks allow you to receive real-time notifications when events occur in your WhatsApp account. CubeConnect processes Meta's webhook events and makes them available through your conversation flows and CRM.

How Webhooks Work

Customer sends message
        ↓
WhatsApp Cloud API
        ↓
Meta sends webhook to CubeConnect
        ↓
CubeConnect processes & stores message
        ↓
Triggers conversation flow / CRM notification

Webhook URL

CubeConnect handles webhook registration automatically when you connect your WhatsApp Business account. The webhook endpoint is:

https://cubeconnect.io/api/webhooks/whatsapp

INFO

You don't need to configure webhooks manually. CubeConnect registers the webhook URL during the WhatsApp account connection process.

Verification Endpoint

GET /api/webhooks/whatsapp

Meta verifies the webhook URL by sending a GET request with a challenge token.

Query Parameters

Parameter	Description
hub.mode	Always subscribe
hub.verify_token	Your webhook verify token
hub.challenge	Challenge string to echo back

Response

Returns the hub.challenge value with status 200 if the verify token matches.

Webhook Delivery

POST /api/webhooks/whatsapp

Meta sends webhook events as POST requests with a JSON payload. Every webhook includes a signature header for verification.

Headers

Header	Description
X-Hub-Signature-256	HMAC-SHA256 signature of the request body
Content-Type	application/json

Payload Structure

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "WABA_ID",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "966501234567",
              "phone_number_id": "PHONE_NUMBER_ID"
            },
            "messages": [...],
            "statuses": [...],
            "contacts": [...]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Event Types

CubeConnect processes the following webhook event types:

Event	Description
Incoming Messages	New messages from customers
Message Status	Delivery and read receipts
Template Status	Template approval/rejection
Account Updates	Account connection changes

See Webhook Events for detailed payload examples.

Security

All webhook requests are verified using HMAC-SHA256 signatures. See Signature Verification for implementation details.