Skip to main content

​
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:
1

A publicly accessible server

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

HTTPS enabled

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

A web framework

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

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.
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

1

Navigate to Agent Configuration

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

Find Call Webhook Section

Scroll to the Call Webhook section and click to expand
3

Enter Webhook URL

Input your publicly accessible HTTPS webhook URL
4

Configure Authentication

Choose authentication method and enter your Bearer token if applicable
5

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:
EventWhen It FiresContains
call.startedCall beginsCaller info, timestamp, custom params
call.answeredCall connectedConnection details, ring duration
transcription.updateUser/agent speaksReal-time text, speaker identification
tool.executedAgent uses a toolTool name, input, output, duration
call.endedCall completesFull 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

  1. Configure your webhook URL and authentication
  2. Save your agent configuration
  3. Make a test call to your agent
  4. Monitor your webhook endpoint for incoming events
  5. 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

​
Best Practices

Security
  • Always use HTTPS endpoints in production
  • Implement Bearer token authentication
  • Rotate tokens periodically
  • Never commit tokens to source control
  • Store tokens in environment variables or secret managers
Reliability
  • Ensure your webhook endpoint returns 200 OK within 5 seconds
  • Implement proper error handling
  • Use async processing for time-consuming operations
  • Monitor webhook delivery and processing
Testing
  • Test webhook configuration before going live
  • Verify all event types are received correctly
  • Test with various call scenarios
  • Monitor webhook logs during initial deployment