Skip to main content

Webhook Configuration

Webhooks allow Cloudonix to communicate with OPBX in real-time. When events occur (like an incoming call), Cloudonix sends HTTP requests to OPBX to notify it and request instructions. This document explains the webhooks used by OPBX.

Webhook Types​

OPBX receives three types of webhooks from Cloudonix:

1. Voice Route Webhook​

Endpoint: /api/voice/route
Purpose: Request call routing instructions
Authentication: Bearer token (Requests API Key)

When a call arrives at a Cloudonix number mapped to OPBX:

OPBX responds with CXML (Cloudonix XML) instructions:

  • Ring an extension
  • Play an IVR menu
  • Route to a ring group
  • Send to voicemail

2. Session Update Webhook​

Endpoint: /api/webhooks/cloudonix/session-update
Purpose: Notify about call state changes
Authentication: HMAC signature verification

Events include:

  • Call initiated
  • Call ringing
  • Call answered
  • Call transferred
  • Call completed (hangup)

3. CDR Webhook​

Endpoint: /api/webhooks/cloudonix/cdr
Purpose: Call Detail Records after call completion
Authentication: HMAC signature verification

Contains complete call information:

  • Duration
  • Disposition (answered, busy, no answer)
  • Caller/callee information
  • Recording URLs (if applicable)

Webhook URLs Generated by OPBX​

When you configure Cloudonix settings, OPBX generates these webhook URLs:

URLPurpose
{base_url}/api/voice/routeVoice routing
{base_url}/api/webhooks/cloudonix/session-updateSession updates
{base_url}/api/webhooks/cloudonix/cdrCall records

Finding Your Webhook URLs​

  1. Go to Settings in OPBX
  2. Look for Webhook URLs section
  3. Copy the URLs you need

Webhook Authentication​

OPBX supports two authentication methods for incoming webhooks:

Bearer Token Authentication​

Used for: Voice Route webhook

Authorization: Bearer {domain_requests_api_key}

OPBX validates the token matches the configured Requests API Key.

HMAC Signature Verification​

Used for: Session Update and CDR webhooks

Cloudonix signs each request with HMAC-SHA256:

X-Cloudonix-Signature: sha256=<signature>
X-Cloudonix-Timestamp: <timestamp>

OPBX verifies the signature using the configured webhook secret.

Configuring Webhook Authentication​

Step 1: Generate Requests API Key​

In OPBX Settings:

  1. Click Generate next to Requests API Key
  2. Copy the generated key
  3. Save the key (you won't see it again)

Step 2: Configure in Cloudonix​

In Cloudonix Portal:

  1. Go to your Voice Application settings
  2. Find webhook authentication settings
  3. Enter the Requests API Key

Step 3: Verify Configuration​

Test by making an inbound call to your Cloudonix number. OPBX should receive the webhook and respond correctly.

Testing Webhooks with ngrok​

For local development, use ngrok to receive webhooks:

Step 1: Start ngrok​

ngrok http 80

Note the HTTPS URL (e.g., https://abc123.ngrok-free.app)

Step 2: Configure OPBX​

In OPBX Settings:

  1. Set Webhook Base URL to your ngrok URL
  2. Save settings

Step 3: View Webhook Requests​

  1. Open ngrok web interface: http://localhost:4040
  2. Click Inspect to see incoming requests
  3. Make a test call to trigger webhooks

Step 4: Review Payloads​

In the ngrok inspector:

  • View request headers
  • View request body
  • Check response from OPBX

Webhook Retry Behavior​

Cloudonix retries webhooks if OPBX doesn't respond:

RetryDelay
1st retry5 seconds
2nd retry30 seconds
3rd retry2 minutes
4th retry10 minutes

If all retries fail, the call proceeds with default Cloudonix behavior (usually ends the call).

Idempotency​

OPBX implements idempotency to handle duplicate webhook deliveries:

  • Each webhook has a unique event ID
  • OPBX caches processed events in Redis
  • Duplicate webhooks return cached responses

This prevents duplicate processing if Cloudonix retries a webhook.

Webhook Payload Examples​

Session Update Payload​

{
  "session_id": "session_abc123",
  "session_uuid": "uuid-xyz789",
  "domain_uuid": "domain_123",
  "direction": "inbound",
  "from": "+1234567890",
  "to": "+0987654321",
  "state": "answered",
  "timestamp": "2026-03-04T10:30:00Z"
}

CDR Payload​

{
  "session_id": "session_abc123",
  "session_uuid": "uuid-xyz789",
  "domain_uuid": "domain_123",
  "direction": "inbound",
  "from": "+1234567890",
  "to": "+0987654321",
  "duration": 180,
  "disposition": "answered",
  "start_time": "2026-03-04T10:30:00Z",
  "end_time": "2026-03-04T10:33:00Z",
  "recording_url": "https://recordings.cloudonix.io/..."
}

Troubleshooting Webhook Issues​

Webhooks Not Received​

  1. Check ngrok: Ensure it's running and URL is correct
  2. Verify base URL: Ensure no trailing slashes
  3. Check Cloudonix Portal: Verify webhook URLs are set

Webhook Authentication Failures​

  1. Bearer token: Verify Requests API Key matches
  2. HMAC signature: Check webhook secret configuration
  3. Clock sync: Ensure server time is accurate

Webhook Timeouts​

  1. Increase timeout: OPBX has 30-second default
  2. Check logs: Review OPBX logs for processing errors
  3. Network issues: Check latency between Cloudonix and OPBX

Monitoring Webhooks​

OPBX Logs​

Webhook requests are logged with:

  • Event type
  • Session/call ID
  • Processing time
  • Any errors

Cloudonix Portal​

Check webhook delivery status in Cloudonix:

  • Success/failure rates
  • Retry history
  • Error messages

Best Practices​

  1. Always use authentication: Enable Requests API Key for production
  2. Use HTTPS: Never use HTTP for webhooks in production
  3. Monitor retries: High retry rates indicate issues
  4. Implement health checks: Ensure webhook endpoints are responsive

Next Steps​

Now that you understand webhooks:

  1. Troubleshooting - Common webhook issues
  2. Call Flow - How calls are routed
  3. Pairing Workflow - Complete the setup

Related Documentation: