Webhook Events

Detailed reference for all webhook events sent by CubeConnect to your system.

TIP

Configure your webhook URL in Settings → Webhook to receive these events. See Webhooks Overview for setup instructions.

Message Events

message.status_updated

Triggered when an outbound message status changes.

{
  "event": "message.status_updated",
  "tenant_id": 1,
  "timestamp": "2026-03-10T14:30:00+03:00",
  "whatsapp_account_id": 5,
  "message_id": "wamid.HBgLMTIzNDU2Nzg5MBUCABIYFjNFQjBGQUFGRTU1MzkA",
  "status": "delivered",
  "recipient": "966501234567",
  "errors": null
}

Status Values

Status	Description
sent	Message accepted by WhatsApp servers
delivered	Message delivered to recipient's device
read	Message read by recipient
failed	Message delivery failed (check errors field)

Failed Status Example

{
  "event": "message.status_updated",
  "tenant_id": 1,
  "timestamp": "2026-03-10T14:30:00+03:00",
  "whatsapp_account_id": 5,
  "message_id": "wamid.xxx",
  "status": "failed",
  "recipient": "966501234567",
  "errors": [
    {
      "code": 131047,
      "title": "Message failed to send because more than 24 hours have passed since the customer last replied."
    }
  ]
}

---

message.received

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

{
  "event": "message.received",
  "tenant_id": 1,
  "timestamp": "2026-03-10T14:30:00+03:00",
  "whatsapp_account_id": 5,
  "wa_message_id": "wamid.HBgLMTIzNDU2Nzg5MBUCABIYFjNFQjBGQUFGRTU1MzkA",
  "from": "966501234567",
  "sender_name": "Mohammed",
  "type": "text",
  "content": "Hello, I need help with my order"
}

Message Types

Type	Content Example
text	Plain text body
image	Caption or [image]
video	Caption or [video]
audio	[audio]
document	Filename or [document]
location	location:24.7136,46.6753
interactive	Button/list selection title
reaction	Emoji character

---

Campaign Events

campaign.created

Triggered when a new campaign is created (scheduled or immediate).

{
  "event": "campaign.created",
  "tenant_id": 1,
  "timestamp": "2026-03-10T14:30:00+03:00",
  "campaign_id": 42,
  "name": "March Promotion",
  "message_type": "template",
  "total_count": 500,
  "status": "pending",
  "scheduled_at": null
}

Field	Description
status	pending (immediate) or scheduled (future)
message_type	template or text
scheduled_at	ISO 8601 timestamp if scheduled, null if immediate

---

campaign.started

Triggered when a scheduled campaign begins execution.

{
  "event": "campaign.started",
  "tenant_id": 1,
  "timestamp": "2026-03-10T14:30:00+03:00",
  "campaign_id": 42,
  "name": "March Promotion",
  "total_count": 500
}

---

campaign.completed

Triggered when all campaign messages have been processed.

{
  "event": "campaign.completed",
  "tenant_id": 1,
  "timestamp": "2026-03-10T15:05:00+03:00",
  "campaign_id": 42,
  "name": "March Promotion",
  "total_count": 500,
  "sent_count": 485,
  "failed_count": 15
}

Field	Description
sent_count	Messages successfully sent
failed_count	Messages that failed to send

---

Template Events

template.submitted

Triggered when a new template is submitted to Meta for approval.

{
  "event": "template.submitted",
  "tenant_id": 1,
  "timestamp": "2026-03-10T14:30:00+03:00",
  "whatsapp_account_id": 5,
  "template_id": 78,
  "name": "order_confirmation",
  "language": "ar",
  "category": "UTILITY",
  "status": "pending"
}

---

template.status_changed

Triggered when Meta changes a template's status (approved, rejected, paused, etc.).

{
  "event": "template.status_changed",
  "tenant_id": 1,
  "timestamp": "2026-03-10T14:30:00+03:00",
  "whatsapp_account_id": 5,
  "template_name": "order_confirmation",
  "status": "approved",
  "meta_template_id": "123456789"
}

Template Status Values

Status	Description
approved	Template approved and ready to use
rejected	Template rejected by Meta
pending	Awaiting Meta review
paused	Paused due to quality issues
disabled	Disabled by Meta

---

Chatbot Events

flow.session_started

Triggered when a customer's message triggers a chatbot flow.

{
  "event": "flow.session_started",
  "tenant_id": 1,
  "timestamp": "2026-03-10T14:30:00+03:00",
  "whatsapp_account_id": 5,
  "session_id": 156,
  "flow_name": "Customer Support",
  "customer_phone": "966501234567"
}

---

flow.session_completed

Triggered when a chatbot flow session finishes (reaches the end step).

{
  "event": "flow.session_completed",
  "tenant_id": 1,
  "timestamp": "2026-03-10T14:35:00+03:00",
  "whatsapp_account_id": 5,
  "session_id": 156,
  "flow_id": 12,
  "customer_phone": "966501234567"
}

---

flow.session_cancelled

Triggered when a customer cancels an active session (sends "cancel", "exit", etc.).

{
  "event": "flow.session_cancelled",
  "tenant_id": 1,
  "timestamp": "2026-03-10T14:32:00+03:00",
  "whatsapp_account_id": 5,
  "session_id": 156,
  "flow_id": 12,
  "customer_phone": "966501234567"
}

---

Quality Events

account.quality_event

Triggered when a recipient blocks or reports your messages.

{
  "event": "account.quality_event",
  "tenant_id": 1,
  "timestamp": "2026-03-10T14:30:00+03:00",
  "whatsapp_account_id": 5,
  "type": "block",
  "user_phone": "966501234567",
  "message_log_id": 4521
}

Type	Description
block	Recipient blocked your number
report	Recipient reported your message as spam

WARNING

Frequent quality events can affect your WhatsApp account's quality rating and reduce your messaging limits. Monitor these events closely.

---

Test Event

webhook.test

Sent when you click Send Test in the webhook settings.

{
  "event": "webhook.test",
  "tenant_id": 1,
  "timestamp": "2026-03-10T14:30:00+03:00",
  "message": "This is a test webhook from CubeConnect"
}

---

Meta Webhook Events (Inbound Reference)

The following events are received from Meta and processed internally by CubeConnect. If you have an outbound webhook configured, CubeConnect forwards the relevant events using the standardized format above.

Incoming Message (Meta Format)

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

Supported Incoming 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

Template Status Update (Meta Format)

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