Webhooks and Integrations

8.1 What are Webhooks

Webhooks allow Voki to send automatic notifications to your external systems when specific events occur. For example, you can be notified when a call is completed to log the service session in your CRM.

Availability: Advanced, Professional, and Enterprise plans.

8.2 Configuring a Webhook

1. Go to "Settings" > "Webhooks" in the Manager Panel
2. Click "New Webhook"
3. Fill in:
   • URL: the endpoint on your system that will receive the notifications (must accept POST)
   • Events: select which events you want to receive
   • Secret: secret key for HMAC validation (automatically generated or defined by you)
4. Click "Save"

8.3 Available Events

Event	Description	When it fires
call.created	Call created	Customer joins the queue
call.assigned	Call assigned	Agent accepts the call
call.started	Call started	WebRTC connection established
call.completed	Call completed	Call ended normally
call.missed	Call missed	Customer left the queue without being served
customer.created	Customer created	New customer registered

8.4 HMAC-SHA256 Signature

Each notification sent by Voki includes an HMAC-SHA256 signature in the X-Voki-Signature header. Use this signature to validate that the request actually came from Voki:

# Validation example in Python
import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode('utf-8'),
        payload.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

// Validation example in Node.js
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return signature === `sha256=${expected}`;
}

8.5 Payload Format

Each notification is sent as an HTTP POST request with the following format:

{
  "event": "call.completed",
  "timestamp": "2026-02-20T14:30:00Z",
  "data": {
    "id": "uuid-da-chamada",
    "status": "completed",
    "duration_seconds": 342,
    "department_id": "uuid-do-departamento",
    "attendant_id": "uuid-do-atendente",
    "customer": {
      "name": "Nome do Cliente",
      "email": "cliente@email.com"
    }
  }
}

Headers sent:

Content-Type: application/json
X-Voki-Signature: sha256=abc123...
X-Voki-Event: call.completed
X-Voki-Delivery: uuid-do-delivery

8.6 Deliveries and Retry

Each webhook delivery attempt is recorded. On the webhook details page, you can:

• View the delivery history
• See the status of each delivery (success, failure, timeout)
• Resend a failed delivery

8.7 Testing a Webhook

To verify that your endpoint is working correctly:

1. In the webhook list, click "Test" next to the desired webhook
2. The system sends a test payload to the configured endpoint
3. The result (success or error) is displayed immediately

---