Webhooks

Webhooks let you receive real-time notifications when events happen in Vois AI. When an event fires, Vois AI sends an HTTP POST request to your endpoint with a JSON payload describing the event.

Use cases

• Log every conversation to your CRM after it ends
• Trigger a follow-up workflow when a caller requests a callback
• Sync agent performance metrics to your analytics platform
• Alert your team when an escalation is requested

Creating a webhook

1. Go to your project → Webhooks
2. Click New Webhook
3. Enter your endpoint URL (must be HTTPS)
4. Select the events you want to receive
5. Copy the signing secret — use it to verify payloads

Verifying payloads

Every request includes a X-Vois-Signature header. Verify it using your signing secret:

import hmac, hashlib

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

Always verify signatures before processing payloads.

Available events

Event	Description
conversation.started	A new conversation session began
conversation.ended	A conversation session ended
message.created	A new message was exchanged
escalation.requested	The agent triggered a human escalation
tool.called	An integration tool was called by the agent

Retry policy

If your endpoint returns a non-2xx status, Vois AI retries with exponential backoff — up to 5 attempts over 24 hours. After all retries fail, the webhook delivery is marked as failed.

Security

• Always use HTTPS endpoints
• Verify the X-Vois-Signature header on every request
• Respond within 10 seconds — processing should happen asynchronously
• Return 200 OK immediately after verifying the signature, then process