Webhook Events

Detailed reference for all webhook event types processed by CubeConnect.

Incoming Messages

Triggered when a customer sends a message to your WhatsApp number.

Text Message

{
  "messages": [
    {
      "from": "966501234567",
      "id": "wamid.HBgLMTIzNDU2Nzg5MBUCABIYFjNFQjBGQUFGRTU1MzkA",
      "timestamp": "1708905600",
      "type": "text",
      "text": {
        "body": "Hello, I need help with my order"
      }
    }
  ],
  "contacts": [
    {
      "profile": {
        "name": "Mohammed"
      },
      "wa_id": "966501234567"
    }
  ]
}

Image Message

{
  "messages": [
    {
      "from": "966501234567",
      "id": "wamid.xxx",
      "timestamp": "1708905600",
      "type": "image",
      "image": {
        "id": "MEDIA_ID",
        "mime_type": "image/jpeg",
        "sha256": "HASH",
        "caption": "Here is my receipt"
      }
    }
  ]
}

Document Message

{
  "messages": [
    {
      "from": "966501234567",
      "id": "wamid.xxx",
      "timestamp": "1708905600",
      "type": "document",
      "document": {
        "id": "MEDIA_ID",
        "mime_type": "application/pdf",
        "sha256": "HASH",
        "filename": "invoice.pdf",
        "caption": "Invoice attached"
      }
    }
  ]
}

Interactive Response (Button)

When a customer clicks a button from an interactive message:

{
  "messages": [
    {
      "from": "966501234567",
      "id": "wamid.xxx",
      "timestamp": "1708905600",
      "type": "interactive",
      "interactive": {
        "type": "button_reply",
        "button_reply": {
          "id": "confirm_order",
          "title": "Confirm Order"
        }
      }
    }
  ]
}

Interactive Response (List)

When a customer selects an item from a list:

{
  "messages": [
    {
      "from": "966501234567",
      "id": "wamid.xxx",
      "timestamp": "1708905600",
      "type": "interactive",
      "interactive": {
        "type": "list_reply",
        "list_reply": {
          "id": "product_001",
          "title": "Premium Package",
          "description": "Full access to all features"
        }
      }
    }
  ]
}

Location Message

{
  "messages": [
    {
      "from": "966501234567",
      "id": "wamid.xxx",
      "timestamp": "1708905600",
      "type": "location",
      "location": {
        "latitude": 24.7136,
        "longitude": 46.6753,
        "name": "Riyadh",
        "address": "King Fahd Road, Riyadh"
      }
    }
  ]
}

Supported Message Types

Type	Description
text	Plain text message
image	Image (JPEG, PNG, WebP, GIF)
video	Video (MP4, 3GP)
audio	Audio/voice note (AAC, OGG, MP3, AMR)
document	Document (PDF, Word, Excel, etc.)
sticker	Sticker (WebP)
location	GPS coordinates with optional name
contacts	Contact card(s)
interactive	Button or list selection response
reaction	Emoji reaction to a message

Message Status Updates

Triggered when a message you sent changes status.

{
  "statuses": [
    {
      "id": "wamid.HBgLMTIzNDU2Nzg5MBUCABIYFjNFQjBGQUFGRTU1MzkA",
      "status": "delivered",
      "timestamp": "1708905660",
      "recipient_id": "966501234567"
    }
  ]
}

Status Values

Status	Description
sent	Message accepted by WhatsApp
delivered	Message delivered to recipient's device
read	Message read by recipient
failed	Message delivery failed

Failed Status

When a message fails, an errors array is included:

{
  "statuses": [
    {
      "id": "wamid.xxx",
      "status": "failed",
      "timestamp": "1708905660",
      "recipient_id": "966501234567",
      "errors": [
        {
          "code": 131047,
          "title": "Message failed to send because more than 24 hours have passed since the customer last replied."
        }
      ]
    }
  ]
}

Template Status Updates

Triggered when a message template's status changes in Meta Business Manager.

{
  "template_status_update": {
    "message_template_id": "123456789",
    "message_template_name": "order_confirmation",
    "message_template_language": "ar",
    "event": "APPROVED"
  }
}

Template Events

Event	Description
APPROVED	Template approved and ready to use
REJECTED	Template rejected by Meta
PENDING_DELETION	Template scheduled for deletion
DISABLED	Template disabled due to quality issues
PAUSED	Template paused due to low quality

Account Updates

Triggered when your WhatsApp Business account status changes.

{
  "account_update": {
    "phone_number": "966501234567",
    "event": "VERIFIED_ACCOUNT"
  }
}

How CubeConnect Processes Webhooks

CubeConnect automatically:

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. Triggers notifications for admin approvals and live chat requests