Webhooks

Overview

Webhooks allow you to receive HTTP POST notifications when events occur in your Voicy account. When a call ends, Voicy sends the full call data — transcript (STT text, not audio), summary, extracted variables, a recording link, and more — to your server in real time. Each agent supports up to 5 webhooks, all firing in parallel. Use them to push call data to your CRM, analytics platform, or any custom integration.

Creating a Webhook

Open Agent Settings

In the Voicy Dashboard, navigate to your agent and open the Settings tab. Scroll down to the Webhooks section and expand it.

Add a Webhook

Click the + button to add a new webhook. Fill in the fields:

Field	Required	Description
Name	Yes	A label to identify this webhook (e.g. “CRM”, “Analytics”, “Slack”)
URL	Yes	The HTTPS endpoint that will receive POST requests
Signing Secret	No	A secret string for HMAC-SHA256 signature verification
Custom Headers	No	Key-value pairs added to every request (e.g. `Authorization: Bearer <token>`)

Click Add to save.

Deploy the Agent

Webhooks are part of the agent configuration. After adding or modifying webhooks, deploy the agent for changes to take effect on phone calls.

Changes take effect immediately for web (test) calls, but phone calls use the deployed version.

Test It

Make a test call from the dashboard’s built-in call simulator. When the call ends, your endpoint will receive a POST request with the full call payload.

Use a service like webhook.site to inspect payloads during development.

Managing Webhooks

Edit — Click the pencil icon on any webhook to change its name, URL, or secret. Leave the secret field blank to keep the existing secret.
Delete — Click the trash icon to remove a webhook.
Limit — Up to 5 webhooks per agent. The badge shows your current count (e.g. “2/5”).

Managing Webhooks via the API

Prompt-based agents’ webhooks can also be set through the Agent API, with the same fields and limits as the dashboard. Changes are deployed immediately — no separate deploy step.

Create — pass webhooks to Create Agent.
Update — pass webhooks to Update Agent. It replaces the agent’s whole list: a webhook you leave out is deleted, and [] removes them all. Omit the field to leave webhooks unchanged.
Read — every Agent response includes webhooks, with has_secret / has_headers in place of the values.

Secrets and headers are write-only. On update, omit them (or send null) to keep what is stored; send "" to remove a secret, or {} to remove all headers. Include each webhook’s id to update it in place — without one, a webhook with the same url is updated.

curl -X PATCH https://api.voicy.co/functions/v1/agent-modify/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer voicy_sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "webhooks": [
      { "id": "6f1c2b1e-8d0a-4c55-9a51-2f4a7e3b9c10", "name": "CRM", "url": "https://crm.example.com/voicy/call-ended" },
      { "name": "Analytics", "url": "https://analytics.example.com/hook", "headers": { "Authorization": "Bearer <token>" } }
    ]
  }'

This keeps the CRM webhook (and its secret), adds an Analytics webhook, and deletes any other webhook on the agent.

Custom Headers

Custom headers let you attach arbitrary HTTP headers to every webhook request — useful when your receiving endpoint requires authentication (e.g. Authorization: Bearer <token>) or a vendor-specific API key header. Limits: Up to 10 headers per webhook. Names must be valid RFC 7230 tokens. Values cannot contain line breaks. Reserved headers that cannot be overridden: Content-Type, x-voicy-event, x-voicy-signature, Host, Content-Length, Transfer-Encoding. Security: Header values are stored server-side and never returned by the API (same treatment as signing secrets). When editing a webhook, leave all value fields blank to preserve the existing headers.

Events

`call_ended`

Fired after all post-call processing completes (summary generation, variable extraction, email notifications). The payload contains the full call data in the same format as the Get Call API. Headers:

Header	Description
Custom headers	Any headers configured for this webhook (order relative to the headers below is not guaranteed)
`Content-Type`	`application/json`
`x-voicy-event`	Event name (`call_ended`)
`x-voicy-signature`	HMAC-SHA256 signature (only if signing secret is configured)

Payload:

{
  "event": "call_ended",
  "call": {
    "call_id": "550e8400-e29b-41d4-a716-446655440000",
    "call_type": "phone_call",
    "call_status": "user_hangup",
    "agent": {
      "name": "My Agent",
      "version": 3
    },
    "from_number": "+972501234567",
    "to_number": "+972521234567",
    "direction": "incoming",
    "start_timestamp": 1710000000000,
    "duration_ms": 45000,
    "transcript": [
      { "timestamp_ms": 0, "role": "agent", "content": "שלום, איך אוכל לעזור?" },
      { "timestamp_ms": 3200, "role": "caller", "content": "אני צריך עזרה" }
    ],
    "summary": "הלקוח ביקש עזרה בנושא...",
    "vars_provided": { "from_number": "+972501234567" },
    "vars_extracted": { "customer_name": "משה" },
    "vars_collected": { "email": "user@example.com" },
    "recording_url": "https://.../recordings/....wav?token=..."
  }
}

recording_url is a signed link to the call recording, valid for 1 hour from when the webhook fires. If you need the recording after it expires, re-fetch it via the Get Call API, which issues a fresh signed URL.

Handling Webhooks

When your server receives a webhook, respond with a 200 status code to acknowledge receipt. Here’s a minimal handler:

const express = require('express');
const app = express();

app.post('/voicy-webhook', express.json(), (req, res) => {
  const { event, call } = req.body;

  console.log(`Event: ${event}`);
  console.log(`Call ID: ${call.call_id}`);
  console.log(`Status: ${call.call_status}`);
  console.log(`Duration: ${call.duration_ms}ms`);

  if (call.summary) {
    console.log(`Summary: ${call.summary}`);
  }

  if (call.vars_extracted) {
    console.log('Extracted vars:', call.vars_extracted);
  }

  res.status(200).send('OK');
});

app.listen(3000);

from flask import Flask, request

app = Flask(__name__)

@app.route('/voicy-webhook', methods=['POST'])
def webhook():
    data = request.json
    event = data['event']
    call = data['call']

    print(f"Event: {event}")
    print(f"Call ID: {call['call_id']}")
    print(f"Status: {call['call_status']}")
    print(f"Duration: {call['duration_ms']}ms")

    if call.get('summary'):
        print(f"Summary: {call['summary']}")

    if call.get('vars_extracted'):
        print(f"Extracted vars: {call['vars_extracted']}")

    return 'OK', 200

Signature Verification

If a signing secret is configured, each webhook request includes an x-voicy-signature header containing an HMAC-SHA256 signature of the raw request body. Always verify signatures in production to ensure requests are genuinely from Voicy.

const crypto = require('crypto');

function verifyWebhook(body, signature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// Express middleware
app.post('/voicy-webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-voicy-signature'];
  if (!verifyWebhook(req.body, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  const event = JSON.parse(req.body);
  console.log('Call ended:', event.call.call_id);
  res.status(200).send('OK');
});

import hmac
import hashlib

def verify_webhook(body: bytes, signature: str, secret: str) -> bool:
    expected = 'sha256=' + hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

# Flask example
from flask import Flask, request, abort

app = Flask(__name__)

@app.route('/voicy-webhook', methods=['POST'])
def webhook():
    signature = request.headers.get('x-voicy-signature', '')
    if not verify_webhook(request.data, signature, WEBHOOK_SECRET):
        abort(401)

    data = request.json
    print(f"Call ended: {data['call']['call_id']}")
    return 'OK', 200

Behavior

Property	Value
Method	POST
Timeout	5 seconds
Retries	None (fire-and-forget)
Content-Type	`application/json`
Parallel	All agent webhooks fire simultaneously

If a webhook endpoint is unreachable or returns an error, the failure is logged but does not affect call processing or other webhooks.

Getting Started

Resources

Overview

Creating a Webhook

Managing Webhooks

Managing Webhooks via the API

Custom Headers

Events

`call_ended`

Handling Webhooks

Signature Verification

Behavior

​Overview

​Creating a Webhook

​Managing Webhooks

​Managing Webhooks via the API

​Custom Headers

​Events

​call_ended

​Handling Webhooks

​Signature Verification

​Behavior

Overview

Creating a Webhook

Managing Webhooks

Managing Webhooks via the API

Custom Headers

Events

`call_ended`

Handling Webhooks

Signature Verification

Behavior