Webhooks Overview

CubeConnect provides two types of webhooks:

1. Outbound Webhooks — CubeConnect sends platform events to your system in real-time
2. Inbound Webhooks — Meta sends WhatsApp events to CubeConnect (handled automatically)

Outbound Webhooks (Your System)

Receive real-time notifications about all platform events directly in your own system. Configure your webhook URL in Settings → Webhook to receive events without polling the API.

Event occurs in CubeConnect
        ↓
CubeConnect queues webhook delivery
        ↓
POST request sent to your webhook URL
        ↓
Your system processes the event

Supported Events

Category	Event	Description
Messages	message.status_updated	Message status change (sent, delivered, read, failed)
	message.received	Incoming message from a customer
Campaigns	campaign.created	New campaign created
	campaign.started	Campaign execution started
	campaign.completed	Campaign finished with sent/failed stats
Templates	template.submitted	New template submitted to Meta
	template.status_changed	Template approved, rejected, or paused
Chatbot	flow.session_started	Chatbot flow session started
	flow.session_completed	Chatbot flow session completed
	flow.session_cancelled	Session cancelled by customer
Quality	account.quality_event	Quality event (block or report)
Test	webhook.test	Connection test ping

See Webhook Events for detailed payload examples.

Setup

1. Go to Settings → Webhook in your dashboard
2. Enter your HTTPS webhook URL
3. Generate a signing secret (optional but recommended)
4. Click Save Settings
5. Use Send Test to verify the connection

Headers

Every outbound webhook includes these headers:

Header	Description
User-Agent	CubeConnect-Webhook/1.0
Content-Type	application/json
Accept	application/json
X-Webhook-Signature	HMAC-SHA256 signature (if signing secret is set)
X-Webhook-Timestamp	ISO 8601 timestamp used for signature

Payload Structure

All outbound webhook events follow this structure:

{
  "event": "message.status_updated",
  "tenant_id": 1,
  "timestamp": "2026-03-10T14:30:00+03:00",
  // ... event-specific data
}

Delivery & Retries

• Webhooks are delivered via a background queue (non-blocking)
• Failed deliveries are retried up to 3 times with 10-second backoff
• Webhook timeout: 10 seconds
• If all retries fail, the event is logged and can be viewed in the Webhook Health Monitor

Security

If you configure a signing secret, every webhook request includes an X-Webhook-Signature header. See Signature Verification for implementation details.

---

Inbound Webhooks (Meta → CubeConnect)

CubeConnect automatically handles webhook registration with Meta when you connect your WhatsApp Business account.

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

Webhook URL

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

INFO

You don't need to configure this 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.

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

Meta Webhook Payload

POST /api/webhooks/whatsapp

{
  "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"
        }
      ]
    }
  ]
}

Meta 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

How CubeConnect Processes Inbound Webhooks

1. Verifies the webhook signature (HMAC-SHA256)
2. Stores all webhook events in the audit log
3. Processes incoming messages through active conversation flows
4. Updates message delivery statuses in real-time
5. Syncs template statuses with your account
6. Forwards events to your outbound webhook URL (if configured)
7. Triggers notifications for admin approvals and live chat requests