Cloudonix Integration

Cloudonix is the cloud communications platform that handles all VoIP and telephony functions for OPBX. OPBX provides the PBX configuration layer, while Cloudonix executes the actual calls.

Understanding the Relationship

OPBX	Cloudonix
PBX configuration and logic	Call execution and SIP services
User management and routing rules	Media processing and call routing
Web interface and APIs	Telephony infrastructure
Call data and reporting	Carrier connectivity

When a call comes in, OPBX returns CXML instructions that tell Cloudonix how to handle it. Cloudonix then manages the actual voice connection.

Prerequisites

Before configuring the integration, you need:

1. A Cloudonix account — sign up at cockpit.cloudonix.io
2. A domain created in your Cloudonix account
3. Domain API key from the Cloudonix cockpit

New to Cloudonix?

Cloudonix offers a free tier for testing. You can sign up without a credit card and start exploring immediately.

Connect your organization to Cloudonix

Who can do this: Owner. The Settings page is not available to other roles (they get an "Access denied" toast).

1. Find your Cloudonix credentials

1. Log into cockpit.cloudonix.io.
2. Select your domain and copy its Domain UUID from the domain settings page.
3. In the API Keys section, create a domain API key or copy an existing one.

2. Enter them in OPBX

1. In OPBX, click your name at the top right and choose Settings.
2. Under Cloudonix Integration, paste the UUID into Cloudonix Domain UUID (format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).
3. Paste the key into Cloudonix Domain API Key.
4. Click Validate and Save Settings. The button stays disabled until both fields hold a value.

A "Saving Settings" overlay is shown while OPBX works. When it is done, the badge next to the button shows Saved, the toast "Settings validated and saved successfully" appears, and "Cloudonix Domain: …" appears under the UUID.

What Validate and Save Settings does, in order:

1. Checks the UUID and key against Cloudonix. Wrong credentials show the Invalid badge and the toast "Validation failed" ("Invalid Cloudonix credentials. Please check your domain UUID and API key."); nothing is saved.
2. Copies the domain name, call timeout and recording format from your Cloudonix domain profile into the form.
3. Saves the settings. A Cloudonix domain can belong to one organization only; a second organization is refused with "This Cloudonix domain is already registered to another organization."
4. Generates a webhook key if the organization has none yet (see Webhook Key).
5. Pushes the call timeout, recording format, session-update URL, CDR URL and webhook key to the Cloudonix domain.
6. Creates or updates the OPBX voice application in Cloudonix and makes it the domain default.

If the save works locally but step 5 or 6 fails, the toast reads "Settings saved, but not synced to Cloudonix" with the reason. Fix the cause (usually the webhook base URL or the API key's rights) and click Validate and Save Settings again.

The other fields on the page (webhook base URL, no-answer timeout, call recording, recording format, embedded dialer domains) are described in Settings.

Webhook Key

Cloudonix authenticates the webhooks it sends to OPBX with a Bearer token, the Cloudonix Domain Requests API Key. OPBX compares it with the stored key on voice routing, status and CDR webhooks. The key is encrypted at rest and shown masked.

You do not need to create it: the first Validate and Save Settings generates one and pushes it to Cloudonix. To replace it, follow Generate a new webhook key: click Generate, copy the key from the New API Key Generated box if you need it, and click Validate and Save Settings. A generated key takes effect only when you save.

Voice routing webhooks are always refused without a valid key. Until an organization has a key, its status and CDR webhooks are accepted without a token and logged as unauthenticated. A platform operator can give every organization a key with php artisan cloudonix:provision-webhook-keys (--dry-run lists the organizations first) and then require it with CLOUDONIX_WEBHOOK_REQUIRE_AUTH=true.

Keep This Secret

Store the webhook key securely. Anyone with this key could potentially send fake call events to your system.

Webhook URL Configuration

OPBX automatically configures the webhook URLs for Cloudonix callbacks. The effective base URL is resolved in this priority order:

1. OPBX_APPLICATION_WEBHOOK_BASEURL environment variable, whenever it is set to a valid http(s) URL (required when OPBX_APPLICATION_MODE=production). The Settings page then shows it read-only as Webhook Base URL (Application Level) ("Managed by system administrator") and hides the endpoint fields.
2. The Webhook Base URL field saved on the Settings page
3. APP_URL from the .env file

The resulting callback URLs are:

Purpose	URL Pattern
Call initiated	{base_url}/api/webhooks/cloudonix/call-initiated
Call status	{base_url}/api/webhooks/cloudonix/call-status
Session updates	{base_url}/api/webhooks/cloudonix/session-update
CDR events	{base_url}/api/webhooks/cloudonix/cdr
Voice routing	{base_url}/api/voice/route
IVR input	{base_url}/api/voice/ivr-input

Behind NAT or Firewall

If your OPBX instance is behind a NAT device or firewall, Cloudonix cannot reach the default webhook URL. You have two options:

Option 1: Environment Variable

Set the application-level webhook base URL in your .env file:

OPBX_APPLICATION_MODE=production
OPBX_APPLICATION_WEBHOOK_BASEURL=https://your-public-domain

Option 2: Settings Page

Enter the public base address in the Webhook Base URL field on the Settings page and click Validate and Save Settings. See Set a webhook base URL. The Domain CDR Endpoint and Domain Session Update Callback URL fields then show the resulting addresses.

Local Development with Ngrok

For local development, use ngrok to expose your local OPBX instance:

1. Add your ngrok authtoken to .env:

   NGROK_AUTHTOKEN=your_token_here

2. Start the tunnel (it is in the dev profile, so a plain up does not start it):

   docker compose --profile dev up -d ngrok

3. Access the ngrok dashboard at http://localhost:4040 to see your public URL.

4. Copy the HTTPS URL, enter it in Webhook Base URL on the Settings page and click Validate and Save Settings.

Ngrok Free Tier

The free ngrok tier provides temporary URLs that change on restart. For persistent development domains, consider upgrading to a paid plan or set NGROK_DOMAIN.

Syncing Extensions

New and changed user extensions are created in Cloudonix as SIP subscribers automatically. When OPBX and Cloudonix differ (for example after the domain is first connected, or subscribers were added in the cockpit), the Sync Extensions button on the Extensions page becomes active:

1. Open Extensions in the sidebar.
2. Click Sync Extensions.

The toast reports how many extensions were created in Cloudonix and how many were imported from Cloudonix. The button is disabled while there is nothing to sync. See Sync with Cloudonix.

Extension Types

Only USER-type extensions sync to Cloudonix as SIP subscribers. Other extension types (conference, IVR, ring groups, AI assistants) are handled internally by OPBX.

Verification

Test your integration by making a call:

1. Configure a DID number in OPBX
2. Route the DID to an extension or ring group
3. Dial the phone number from an external phone
4. Verify the call connects to the expected destination

Check the call logs in both OPBX and the Cloudonix cockpit to confirm proper call flow.

Related API Endpoints

Method	Endpoint	Purpose
GET	/v1/settings/cloudonix	Retrieve current Cloudonix settings (masked keys)
PUT	/v1/settings/cloudonix	Update settings and sync to Cloudonix
POST	/v1/settings/cloudonix/validate	Validate domain credentials
POST	/v1/settings/cloudonix/generate-requests-key	Generate webhook auth key
GET	/v1/settings/cloudonix/outbound-trunks	List available voice trunks

See the OPBX REST API reference for full schemas.

Troubleshooting

Issue	Solution
"Invalid credentials" error	Verify Domain UUID and API key are correct and belong to the same domain
Webhooks not received	Check webhook base URL is publicly accessible; verify firewall rules
Calls fail to connect	Ensure extensions are synced to Cloudonix (Sync Extensions); check SIP credentials
"Settings saved, but not synced to Cloudonix"	The local save worked but the push to Cloudonix or the voice application setup failed. Check the reason in the toast and docker compose logs app, then save again
"This Cloudonix domain is already registered to another organization."	Each Cloudonix domain can be connected to one OPBX organization only
No audio on calls	Verify NAT settings; check Cloudonix media server connectivity
Voice app update fails	OPBX reconciles stale voice apps automatically; verify the stored voice_application_name matches Cloudonix

Support

For Cloudonix-specific issues, consult the Cloudonix documentation. For OPBX integration issues, check the application logs with docker compose logs -f app.