3CX Webhook Reference

Pre-authentication response

Before a request is authenticated, WhatsApp Gateway returns a generic response for unknown or disabled integrations, missing or wrong secrets, IP allowlist failures, stale timestamps, and invalid signatures.

{
  "success": false,
  "error": "invalid_3cx_webhook",
  "message": "Invalid 3CX webhook request."
}

After authentication, safe specific errors may include payload_too_large, webhook_rate_limited, invalid_json, module_not_enabled, missing_phone, missing_message_text, message_purpose_not_allowed, recipient_suppressed, sending_throttled, policy_violation, or gateway_send_failed.

Supported event types

Outbound reply example

The outbound_message event is a 3CX reply into an active WhatsApp conversation. The WhatsApp user must have messaged first, and the last inbound message must be within the active conversation window.

{
  "event_type": "outbound_message",
  "to": "+966500000000",
  "message_text": "Your support request has been updated.",
  "message_purpose": "support",
  "conversation_id": "3cx-chat-123",
  "agent_extension": "101"
}