Webhook Setup

Webhooks notify your server when events occur in Vocobase, such as a call status changing or a session completing. Instead of polling the API, you receive a POST request with the event payload.

What webhooks are for

Vocobase sends two classes of webhook events to each enabled webhook endpoint:

Event	Purpose	Use it for
`call.status.updated`	Real-time phone call lifecycle updates from the telephony provider	Partner queue orchestration, live UI state, freeing concurrency when the call reaches a terminal status
`session.completed`	Final Vocobase session data after the bot and post-call pipeline finish	Transcript, recording URL, credits, variables, extraction, and final call metadata

For outbound telephony calls, use call.status.updated to know what is happening right now. Use session.completed only when you need final post-call data. call.status.updated includes:

Current normalized call status
Previous status, when available
Final call disposition and answer classification when available
Hangup cause/source when the provider supplied them
Whether the status is terminal
Whether the call slot/concurrency can be released
Account-wide concurrency snapshot for queue orchestration
Provider and raw provider status for debugging

session.completed includes:

Full conversation transcript with timestamps
Call duration and credits used
Recording download URL (if recording was enabled)
Pre-call variables and post-call extraction results
Call metadata (phone numbers, provider, direction)

Configure webhook endpoints

Use webhook endpoints to send the same event stream to one or more destinations, such as prod, staging, or an internal audit receiver. Each endpoint has its own URL, enabled flag, delivery history, and signing secret.

curl -X POST https://api.vocobase.com/api/v2/config/webhooks \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "prod",
    "url": "https://your-server.com/webhooks/vocobase"
  }'

The response contains a secret that you must save:

{
  "success": true,
  "data": {
    "id": "12345678-abcd-1234-abcd-123456789012",
    "label": "prod",
    "url": "https://your-server.com/webhooks/vocobase",
    "enabled": true,
    "last_delivery_at": null,
    "last_delivery_status": null,
    "created_at": "2026-05-25T10:30:00.000Z",
    "updated_at": "2026-05-25T10:30:00.000Z",
    "secret": "whsec_a1b2c3d4e5f6g7h8i9j0...",
    "message": "Save this secret — it will not be shown again."
  }
}

The endpoint secret is only shown once. Store it in your environment variables immediately. If you lose it, rotate the endpoint secret with POST /config/webhooks/{id}/rotate-secret.

Manage endpoints

List configured endpoints:

curl https://api.vocobase.com/api/v2/config/webhooks \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012"

Update a label, URL, or enabled state:

curl -X PATCH https://api.vocobase.com/api/v2/config/webhooks/12345678-abcd-1234-abcd-123456789012 \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": false }'

Rotate a signing secret:

curl -X POST https://api.vocobase.com/api/v2/config/webhooks/12345678-abcd-1234-abcd-123456789012/rotate-secret \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012"

Delete an endpoint:

curl -X DELETE https://api.vocobase.com/api/v2/config/webhooks/12345678-abcd-1234-abcd-123456789012 \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012"

Labels and limits

Labels must be lowercase letters, numbers, and hyphens; start with a letter or number; and be 1-31 characters.
The default label is reserved for the legacy single-webhook compatibility route.
Each partner can configure up to 5 webhook endpoints.
Only enabled endpoints receive new events.
Endpoints receive all webhook event types. Branch on the top-level event field in your handler.
Each endpoint signs requests with its own secret.

Existing integrations that use PUT /api/v2/config/webhook still work. That route now creates or replaces the reserved default endpoint and returns a webhook_secret. New integrations should use /config/webhooks.

Requirements

Your webhook endpoint must:

Accept POST requests
Use HTTPS (HTTP URLs are rejected)
Return a 2xx status code within 10 seconds
Be publicly accessible from the internet

Signature verification

Every webhook request includes an X-Webhook-Signature header for verifying authenticity. The signature is computed as an HMAC-SHA256 hash of timestamp.body using your webhook secret.

Header format

X-Webhook-Signature: sha256=<hex-encoded-hmac>
X-Webhook-Timestamp: <iso-8601-timestamp>

Verification steps

Extract the X-Webhook-Signature and X-Webhook-Timestamp headers
Construct the signed payload: {timestamp}.{raw_request_body}
Compute HMAC-SHA256 using your webhook secret
Compare the computed signature with the one in the header

Node.js example

const crypto = require("crypto");

// IMPORTANT: Use express.raw() or express.text() middleware on your webhook
// route so req.body is the raw string, not a parsed JSON object.
// Example: app.post("/webhooks/vocobase", express.text({ type: "*/*" }), handler)
function verifyWebhookSignature(req, webhookSecret) {
  const signature = req.headers["x-webhook-signature"];
  const timestamp = req.headers["x-webhook-timestamp"];
  // req.body must be the raw request body string, not a parsed object
  const body = typeof req.body === "string" ? req.body : req.rawBody?.toString() || JSON.stringify(req.body);

  // Reject requests older than 5 minutes to prevent replay attacks
  const timestampMs = new Date(timestamp).getTime();
  if (Math.abs(Date.now() - timestampMs) > 300_000) {
    throw new Error("Webhook timestamp too old");
  }

  // Compute expected signature
  const signedPayload = `${timestamp}.${body}`;
  const expectedSignature =
    "sha256=" +
    crypto
      .createHmac("sha256", webhookSecret)
      .update(signedPayload)
      .digest("hex");

  // Timing-safe comparison
  if (
    !crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expectedSignature)
    )
  ) {
    throw new Error("Invalid webhook signature");
  }

  return true;
}

// Express.js handler
app.post("/webhooks/vocobase", (req, res) => {
  try {
    verifyWebhookSignature(req, process.env.VOCOBASE_WEBHOOK_SECRET);
  } catch (err) {
    return res.status(401).json({ error: err.message });
  }

  const event = req.body;
  console.log("Received event:", event.event, event.data?.session_id);

  // Process the webhook asynchronously
  processWebhookAsync(event);

  // Return 200 immediately
  res.status(200).json({ received: true });
});

Python example

import hmac
import hashlib
import os
from datetime import datetime, timezone
from flask import Flask, request, jsonify

app = Flask(__name__)

def verify_webhook_signature(request, webhook_secret):
    signature = request.headers.get("X-Webhook-Signature")
    timestamp = request.headers.get("X-Webhook-Timestamp")
    body = request.get_data(as_text=True)

    # Reject requests older than 5 minutes
    ts = datetime.fromisoformat(timestamp.replace("Z", "+00:00"))
    age = abs((datetime.now(timezone.utc) - ts).total_seconds())
    if age > 300:
        raise ValueError("Webhook timestamp too old")

    # Compute expected signature
    signed_payload = f"{timestamp}.{body}"
    expected = "sha256=" + hmac.new(
        webhook_secret.encode(),
        signed_payload.encode(),
        hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(signature, expected):
        raise ValueError("Invalid webhook signature")

@app.post("/webhooks/vocobase")
def handle_webhook():
    try:
        verify_webhook_signature(request, os.environ["VOCOBASE_WEBHOOK_SECRET"])
    except ValueError as e:
        return jsonify({"error": str(e)}), 401

    event = request.json
    # Process asynchronously, return immediately
    return jsonify({"received": True}), 200

Always verify signatures in production. Skipping verification exposes your endpoint to forged requests.

Getting Started

Guides

Partner Onboarding

API Reference

Webhooks

Telephony

Webhook Setup

Webhook Setup

What webhooks are for

Configure webhook endpoints

Manage endpoints

Labels and limits

Requirements

Signature verification

Header format

Verification steps

Node.js example

Python example

Next steps

Webhook Payloads

Error Handling

​Webhook Setup

​What webhooks are for

​Configure webhook endpoints

​Manage endpoints

​Labels and limits

​Requirements

​Signature verification

​Header format

​Verification steps

​Node.js example

​Python example

​Next steps

Webhook Payloads

Error Handling

Webhook Setup

What webhooks are for

Configure webhook endpoints

Manage endpoints

Labels and limits

Requirements

Signature verification

Header format

Verification steps

Node.js example

Python example

Next steps