> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryhamsa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuring Webhooks in Dashboard

> Set up webhook endpoints for your AI agents using the Hamsa dashboard

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

<CardGroup cols={2}>
  <Card title="Real-time Events" icon="bolt">
    Instant notifications as calls progress, from start to completion
  </Card>

  <Card title="Call Data" icon="database">
    Full transcripts, recordings, and extracted information
  </Card>

  <Card title="Custom Parameters" icon="sliders">
    Pass ANY custom data that gets echoed back for identification
  </Card>

  <Card title="Secure Delivery" icon="shield">
    HTTPS-only with Bearer token authentication support
  </Card>
</CardGroup>

## Prerequisites

Before setting up webhooks, ensure you have:

<Steps>
  <Step title="A publicly accessible server">
    Your webhook endpoint must be reachable from the internet. Use ngrok for local development.
  </Step>

  <Step title="HTTPS enabled">
    All webhook URLs must use HTTPS. HTTP endpoints will be rejected.
  </Step>

  <Step title="A web framework">
    Express.js, Flask, FastAPI, or any framework that can handle POST requests.
  </Step>

  <Step title="Basic authentication setup">
    Prepare to implement Bearer token authentication (recommended for production).
  </Step>
</Steps>

## Webhook URL Requirements

<Warning>
  **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
</Warning>

**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:

```bash theme={null}
# 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:

```json theme={null}
{
  "webhookUrl": "https://abc123.ngrok.io/webhook",
  "webhookAuth": {
    "authKey": "noAuth"
  }
}
```

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

### Option 2: Bearer Token Authentication (Recommended)

Use for production environments:

```json theme={null}
{
  "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:**

```bash theme={null}
# 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

<Steps>
  <Step title="Navigate to Agent Configuration">
    Go to your agent's configuration page in the Hamsa dashboard
  </Step>

  <Step title="Find Call Webhook Section">
    Scroll to the **Call Webhook** section and click to expand
  </Step>

  <Step title="Enter Webhook URL">
    Input your publicly accessible HTTPS webhook URL
  </Step>

  <Step title="Configure Authentication">
    Choose authentication method and enter your Bearer token if applicable
  </Step>

  <Step title="Save Configuration">
    Save your agent configuration to activate the webhook
  </Step>
</Steps>

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

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

```bash theme={null}
# 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:**

```bash theme={null}
# 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:

<CardGroup cols={2}>
  <Card title="Build Webhook Handlers" href="/developers/guides/webhook-integration" icon="code">
    Complete guide to implementing webhook endpoints and processing events
  </Card>

  <Card title="Webhooks Feature Overview" href="/overview/features/webhooks" icon="book">
    Learn about webhook concepts and patterns
  </Card>

  <Card title="Outcomes Configuration" href="/agents/single-prompt/configure-settings" icon="sliders">
    Configure what data your agent extracts
  </Card>

  <Card title="Testing Webhooks" href="/agents/testing/introduction" icon="flask">
    Test your webhook integration
  </Card>
</CardGroup>