Configuring Webhooks

Learn how to configure webhook endpoints for your AI agents to receive real-time call events and conversation data.

What are Webhooks?

Webhooks allow your applications to receive real-time notifications about call events, transcriptions, and conversation outcomes. When a voice call completes or specific events occur, Hamsa sends HTTP POST requests to your configured endpoint with relevant data.

Real-time Events

Instant notifications as calls progress, from start to completion

Call Data

Full transcripts, recordings, and extracted information

Custom Parameters

Pass ANY custom data that gets echoed back for identification

Secure Delivery

HTTPS-only with Bearer token authentication support

Prerequisites

Before setting up webhooks, ensure you have:

A publicly accessible server

Your webhook endpoint must be reachable from the internet. Use ngrok for local development.

HTTPS enabled

All webhook URLs must use HTTPS. HTTP endpoints will be rejected.

A web framework

Express.js, Flask, FastAPI, or any framework that can handle POST requests.

Basic authentication setup

Prepare to implement Bearer token authentication (recommended for production).

Webhook URL Requirements

HTTPS Required:

All webhook URLs must use HTTPS protocol
HTTP endpoints will be rejected
Self-signed certificates are not supported
Certificate must be valid and not expired

Valid Examples:

✅ https://api.yourcompany.com/webhook/hamsa
✅ https://webhook.example.com/hamsa/events
✅ https://your-app.herokuapp.com/webhooks/calls

❌ http://api.yourcompany.com/webhook (HTTP not allowed)
❌ https://192.168.1.100/webhook (local IPs not accessible)
❌ https://localhost:3000/webhook (localhost not accessible)

Local Development Setup

For local development, use ngrok to expose your localhost:

# Install ngrok
npm install -g ngrok
# or brew install ngrok

# Start your local server
node server.js  # Runs on port 3000

# In another terminal, start ngrok
ngrok http 3000

# Use the ngrok HTTPS URL in your webhook configuration
# Example: https://abc123.ngrok.io/webhook

Authentication Options

Option 1: No Authentication (Development Only)

Use for development or testing:

{
  "webhookUrl": "https://abc123.ngrok.io/webhook",
  "webhookAuth": {
    "authKey": "noAuth"
  }
}

Not recommended for production. Anyone who discovers your webhook URL can send requests to it.

Option 2: Bearer Token Authentication (Recommended)

Use for production environments:

{
  "webhookUrl": "https://api.yourcompany.com/webhook",
  "webhookAuth": {
    "authKey": "bearer",
    "authSecret": "Bearer your_secret_token_here"
  }
}

Token Format Requirements:

Must include the word “Bearer” followed by your token
Example: Bearer sk_live_abc123xyz789
Token should be long and randomly generated
Never commit tokens to source control

Generating Secure Tokens:

# Generate a random token (Linux/Mac)
openssl rand -base64 32

# Or use Node.js
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

# Or use Python
python -c "import secrets; print(secrets.token_urlsafe(32))"

Adding Webhook to Your Agent

Navigate to Agent Configuration

Go to your agent’s configuration page in the Hamsa dashboard

Find Call Webhook Section

Scroll to the Call Webhook section and click to expand

Enter Webhook URL

Input your publicly accessible HTTPS webhook URL

Configure Authentication

Choose authentication method and enter your Bearer token if applicable

Save Configuration

Save your agent configuration to activate the webhook

Webhooks are configured per agent. Each agent can have its own webhook URL and authentication settings.

Event Types

Your webhook receives various events throughout a call’s lifecycle:

Event	When It Fires	Contains
call.started	Call begins	Caller info, timestamp, custom params
call.answered	Call connected	Connection details, ring duration
transcription.update	User/agent speaks	Real-time text, speaker identification
tool.executed	Agent uses a tool	Tool name, input, output, duration
call.ended	Call completes	Full transcript, recording, outcome data

Testing Your Webhook

Test with cURL

# Test basic connectivity
curl -X POST https://your-endpoint.com/webhook \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_secret_token" \
  -d '{"test": true}'

# Should return 200 OK

Test from Dashboard

Configure your webhook URL and authentication
Save your agent configuration
Make a test call to your agent
Monitor your webhook endpoint for incoming events
Verify you receive the call.ended event with full data

Common Issues

Webhook Not Receiving Data

Possible Causes:

Webhook URL is not publicly accessible
Webhook URL not configured in Hamsa dashboard
Firewall/security rules blocking POST requests
Server not running or crashed
HTTPS certificate invalid

Solutions:

# Test your webhook endpoint
curl -X POST https://your-endpoint.com/webhook \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_token" \
  -d '{"test": true}'

# Should return 200 OK

Authentication Failures

Possible Causes:

Bearer token mismatch
Token format incorrect (missing “Bearer” prefix)
Token changed in dashboard but not in code

Solution:

Verify token format: Bearer sk_live_abc123xyz789
Ensure token matches exactly between dashboard and your code
Check for extra spaces or formatting issues

Next Steps

Now that you’ve configured webhooks in the dashboard, learn how to implement webhook handlers:

Build Webhook Handlers

Complete guide to implementing webhook endpoints and processing events

Webhooks Feature Overview

Learn about webhook concepts and patterns

Outcomes Configuration

Configure what data your agent extracts

Testing Webhooks

Test your webhook integration

Dashboard

Agents

Publishing

Variables

Tools

Knowledge Base

Batch Calls

Call History

Phone Numbers

Configuration

Configuring Webhooks in Dashboard

Configuring Webhooks

What are Webhooks?

Real-time Events

Call Data

Custom Parameters

Secure Delivery

Prerequisites

Webhook URL Requirements

Local Development Setup

Authentication Options

Option 1: No Authentication (Development Only)

Option 2: Bearer Token Authentication (Recommended)

Adding Webhook to Your Agent

Event Types

Testing Your Webhook

Test with cURL

Test from Dashboard

Common Issues

Webhook Not Receiving Data

Authentication Failures

Next Steps

Build Webhook Handlers

Webhooks Feature Overview

Outcomes Configuration

Testing Webhooks

​Configuring Webhooks

​What are Webhooks?

Real-time Events

Call Data

Custom Parameters

Secure Delivery

​Prerequisites

​Webhook URL Requirements

​Local Development Setup

​Authentication Options

​Option 1: No Authentication (Development Only)

​Option 2: Bearer Token Authentication (Recommended)

​Adding Webhook to Your Agent

​Event Types

​Testing Your Webhook

​Test with cURL

​Test from Dashboard

​Common Issues

​Webhook Not Receiving Data

​Authentication Failures

​Next Steps

Build Webhook Handlers

Webhooks Feature Overview

Outcomes Configuration

Testing Webhooks

Configuring Webhooks

What are Webhooks?

Prerequisites

Webhook URL Requirements

Local Development Setup

Authentication Options

Option 1: No Authentication (Development Only)

Option 2: Bearer Token Authentication (Recommended)

Adding Webhook to Your Agent

Event Types

Testing Your Webhook

Test with cURL

Test from Dashboard

Common Issues

Webhook Not Receiving Data

Authentication Failures

Next Steps