Webhooks

Webhooks let you receive real-time notifications when events occur in Voxagent. When an event triggers, the platform sends an HTTP POST request to your specified URL with the event payload.

Creating a Webhook Subscription

1. Navigate to Webhooks in the sidebar.
2. Click + Create Webhook.
3. Fill in the configuration:
   • URL: The endpoint where Voxagent will send event payloads (e.g., https://your-server.com/webhooks/speaknode).
   • Description: A note describing the purpose of this webhook (e.g., "CRM sync for completed conversations").
   • Event Types: Select which events should trigger this webhook.
   • Enabled: Toggle the webhook on or off.
4. Click Save.

Event Types

Webhook Secret and Signature Verification

Each webhook subscription is assigned a Webhook Secret. Use this secret to verify that incoming requests genuinely originate from Voxagent.

How Verification Works

Voxagent signs each webhook request using HMAC-SHA256:

1. The platform computes an HMAC-SHA256 hash of the request body using your webhook secret as the key.
2. The resulting signature is included in the request header.
3. Your server should compute the same hash and compare it to the header value.

Verification Example

import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode("utf-8"),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Viewing Request History

Voxagent logs every webhook delivery attempt so you can debug issues.

1. Open a webhook subscription from the Webhooks list.
2. Scroll down to the Request History section.
3. Each entry shows:
   • Timestamp: When the request was sent.
   • HTTP Status: The response status code from your server (e.g., 200, 500, timeout).
   • Payload: The JSON body that was sent.
   • Response: The response body returned by your server.

Troubleshooting