Skip to main content

​
What are Webhooks?

Webhooks allow your applications to receive real-time notifications about call events, transcriptions, and conversation outcomes. Configure a webhook endpoint to get instant updates when calls start, end, or when your agent completes specific actions, enabling seamless integration with your existing systems.
Key Features:
  • Real-time Events - Instant notifications as calls progress
  • Call Transcriptions - Full conversation text sent to your endpoint
  • Outcome Data - Structured data extracted from conversations
  • Secure Authentication - Bearer token support for secure webhooks
  • HTTPS Only - All webhooks use encrypted connections

​
How It Works

Webhook integration follows a simple flow:
  1. Configure - Add webhook URL to your agent settings
  2. Authentication - Set up Bearer token (optional but recommended)
  3. Call Event - User calls your agent or agent makes outbound call
  4. Real-time Push - Hamsa sends POST requests to your webhook
  5. Process - Your server receives and processes event data

​
Event Types

Your webhook receives various events throughout a call’s lifecycle: Call Events
  • call.started - Call begins
  • call.answered - Call connected
  • call.ended - Call completes with full transcript and outcome data
Conversation Events
  • transcription.update - Real-time transcription as user/agent speaks
  • tool.executed - Agent executes a tool (API call, knowledge base query)
Data Included
  • Caller information and phone numbers
  • Full conversation transcripts
  • Call duration and timestamps
  • Structured outcome data based on your schema
  • Tool execution results

​
Common Use Cases

Call Analytics
  • Track call metrics and build dashboards
  • Monitor agent performance and resolution rates
  • Analyze conversation patterns and trends
CRM Integration
  • Automatically update customer records
  • Create activity logs for each call
  • Sync conversation outcomes to customer profiles
Notification Systems
  • Alert teams about urgent calls
  • Send email summaries of conversations
  • Post call summaries to Slack or Teams
Data Warehousing
  • Stream events to your data warehouse
  • Build comprehensive analytics pipelines
  • Track long-term trends and insights

​
Getting Started

Choose your implementation path based on how you want to work with webhooks:

Configure in Dashboard

Set up webhooks using the web interface. Perfect for configuring webhook URLs, authentication, and testing integrations.

Integrate via API

Build webhook handlers programmatically. Ideal for processing events, implementing retry logic, and scaling integrations.

​
Learn More

Outcomes

Define what data to extract from calls

Telephony

Configure phone numbers with webhooks

Single Prompt Agents

Set up webhooks in Single Prompt Agents

Flow Agents

Configure webhooks in Flow Agents

​
Best Practices

Response Time
  • Always return a 200 status within 5 seconds to avoid timeouts
  • Queue events for background processing instead of blocking the response
  • Use async processing patterns for time-consuming operations
Security
  • Always use HTTPS endpoints
  • Implement Bearer token authentication
  • Validate all incoming data before processing
  • Use strong, randomly generated tokens
  • Rotate tokens periodically
Reliability
  • Implement idempotency using callId to handle duplicate events
  • Add retry logic with exponential backoff
  • Monitor webhook endpoint health and uptime
  • Log authentication failures and processing errors
Data Processing
  • Validate webhook payloads with schemas
  • Handle all event types gracefully
  • Store events for audit trails
  • Monitor event delivery rates