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. Which of your endpoints receive a given event depends on the endpoint’s scope and its event allowlist — see Scoping & Event Filtering:

Event	Purpose	Use it for
`call.status.updated`	Real-time phone call lifecycle updates from the telephony provider	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 fan events out 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 — plus its own scope (account-wide or bound to one agent) and its own event allowlist, so two endpoints on the same account can receive completely different streams. A new endpoint created as below is account-wide with no allowlist, which means it receives every event type from every agent.

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,
    "agent_id": null,
    "agent_name": null,
    "events": [],
    "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."
  }
}

agent_id: null means account-wide and events: [] means every event type; agent_name mirrors the scoped agent’s display name and is null for an account-wide endpoint. All three are returned on every endpoint object, from every route that returns one. See Scoping & Event Filtering to narrow either one.

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"

The response is { "endpoints": [...], "available_events": [...] }, where available_events is the live event catalog. Narrow the list with ?agent_id: pass an agent id for that agent’s endpoints, or the literal none for account-wide endpoints only. Omit it to get every endpoint on the account. Update a label, URL, enabled state, or event allowlist:

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"

Send a test event

Fires a real, signed webhook.test delivery through the production queue, so it exercises signing, SSRF validation, and retries, and appears in delivery history like any other event:

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

{
  "success": true,
  "data": { "delivery_id": "d1e2f3a4-5678-90ab-cdef-1234567890ab" }
}

A 202 means the delivery was enqueued, not that your server accepted it. Check delivery history for the outcome. A disabled endpoint is refused with 409 ENDPOINT_DISABLED.

Test events ignore the endpoint’s event allowlist by design — a test must reach the endpoint being tested even when its events filter would exclude everything. Handle or ignore webhook.test explicitly in your handler.

Delivery history

curl "https://api.vocobase.com/api/v2/config/webhooks/12345678-abcd-1234-abcd-123456789012/deliveries?limit=25" \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012"

{
  "success": true,
  "data": {
    "deliveries": [
      {
        "id": "d1e2f3a4-5678-90ab-cdef-1234567890ab",
        "event_type": "session.completed",
        "status": "DELIVERED",
        "attempts": 2,
        "max_attempts": 5,
        "session_id": "5f6e7d8c-1234-5678-9abc-def012345678",
        "url": "https://your-server.com/webhooks/vocobase",
        "last_response_status": 200,
        "last_error": null,
        "next_attempt_at": null,
        "last_attempt_at": "2026-05-25T10:31:04.000Z",
        "delivered_at": "2026-05-25T10:31:04.000Z",
        "created_at": "2026-05-25T10:30:59.000Z"
      }
    ],
    "next_cursor": null
  }
}

Query parameters: limit (default 25, max 100), cursor for pagination, and status to filter by PENDING, DELIVERING, DELIVERED, FAILED, or EXHAUSTED. Page by passing the previous response’s next_cursor; a null cursor means there are no more pages. max_attempts is 5 — the initial delivery plus four retries. See Error Handling for the schedule.

Labels and limits

Labels must be lowercase letters, numbers, and hyphens; start with a letter or number; and be 1-31 characters.
Labels are unique per account, not per scope, so the same label cannot be reused on two agents. The second one is refused with 409 LABEL_TAKEN.
The default label is reserved for the legacy single-webhook compatibility route.
Up to 5 endpoints per scope — the account gets its own 5, and so does each agent.
Only enabled endpoints receive new events.
Endpoints receive every event type unless you set an events allowlist. See Scoping & Event Filtering. Branch on the top-level event field in your handler either way.
Endpoints are account-wide unless created with an agent_id, which is set once and cannot be changed afterwards.
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.

Webhooks vs lifecycle hooks

Webhooks are a one-way, signed, retried event feed: Vocobase tells you something happened, in a fixed payload shape, and keeps retrying until your server accepts it. Lifecycle hooks (PRE_CALL / POST_CALL, configured under an agent’s Actions) are action runners: they call your API with a body you template, and the response is used — pre-call output is merged into the prompt’s variables, post-call output can consume extraction results. Use a webhook to know something happened. Use a lifecycle hook to fetch or push data as part of the call. See Scoping & Event Filtering for a full comparison.

Next steps

Scoping & Event Filtering

Bind endpoints to one agent and subscribe to specific event types.

Webhook Payloads

See the full payload structure for each event type.

Error Handling

Learn about retry behavior and best practices.

Getting Started

Building Agents

Making Calls

Receiving Calls

After the Call

Telephony Providers

Advanced

API Reference

Endpoints

Webhook Setup

Webhook Setup

What webhooks are for

Configure webhook endpoints

Manage endpoints

Send a test event

Delivery history

Labels and limits

Requirements

Signature verification

Header format

Verification steps

Node.js example

Python example

Webhooks vs lifecycle hooks

Next steps

Scoping & Event Filtering

Webhook Payloads

Error Handling

​Webhook Setup

​What webhooks are for

​Configure webhook endpoints

​Manage endpoints

​Send a test event

​Delivery history

​Labels and limits

​Requirements

​Signature verification

​Header format

​Verification steps

​Node.js example

​Python example

​Webhooks vs lifecycle hooks

​Next steps

Scoping & Event Filtering

Webhook Payloads

Error Handling

Webhook Setup

What webhooks are for

Configure webhook endpoints

Manage endpoints

Send a test event

Delivery history

Labels and limits

Requirements

Signature verification

Header format

Verification steps

Node.js example

Python example

Webhooks vs lifecycle hooks

Next steps