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

# Webhooks

> Send real-time call events to any system. Build custom workflows with n8n, Zapier, or any automation tool.

Webhooks allow your VoiceFlows to send real-time notifications to external systems when call events occur. Use webhooks to integrate with CRMs, trigger automations, update databases, or connect to any HTTP endpoint.

## How Webhooks Work

1. You register a webhook endpoint (your server URL) under **Connections**
2. You enable webhooks on a VoiceFlow and select which events to send
3. When a call event occurs, EolasFlow sends a POST request to your endpoint
4. Your server processes the data and responds with a 2xx status code

## Webhook Events

EolasFlow can notify you about these call events:

| Event              | Description                           |
| ------------------ | ------------------------------------- |
| `call.initiated`   | Call request created, dialing started |
| `call.ringing`     | Destination phone is ringing          |
| `call.answered`    | Call was answered                     |
| `call.in_progress` | Active conversation is happening      |
| `call.completed`   | Call ended successfully               |
| `call.failed`      | Call failed to connect                |
| `call.no_answer`   | No one answered the call              |
| `call.busy`        | Line was busy                         |
| `call.cancelled`   | Call was cancelled before connecting  |
| `call.voicemail`   | Call went to voicemail                |

<Tip>
  The `call.completed` event includes the full transcript, recording URL, and call duration—ideal for post-call processing.
</Tip>

## Setting Up Webhooks

### Step 1: Register a Webhook Endpoint

First, register your server's webhook URL:

<Steps>
  <Step title="Navigate to Integrations">
    Go to **Connections → Webhooks**.
  </Step>

  <Step title="Add New Endpoint">
    Click **Add Endpoint** and enter:

    * **Name:** A descriptive name (e.g., "CRM Integration")
    * **URL:** Your webhook endpoint URL
  </Step>

  <Step title="Configure Authentication">
    Choose how to authenticate requests to your server:

    * **None:** No authentication
    * **Bearer Token:** Authorization header with Bearer token
    * **API Key (Header):** Custom header with API key
    * **API Key (Query):** API key as URL parameter
    * **Basic Auth:** HTTP Basic authentication
    * **Custom Header:** Custom header name and value
  </Step>

  <Step title="Optional: Add Signing Secret">
    Add a signing secret to verify webhook payloads using HMAC-SHA256.
  </Step>

  <Step title="Test Connection">
    Click **Test** to verify your endpoint is reachable.
  </Step>

  <Step title="Save">
    Click **Save** to register the endpoint.
  </Step>
</Steps>

### Step 2: Enable Webhooks on a VoiceFlow

<Steps>
  <Step title="Open VoiceFlow Settings">
    Go to **VoiceFlows** and click on your VoiceFlow.
  </Step>

  <Step title="Navigate to Webhooks Tab">
    Click the **Webhooks** tab in VoiceFlow settings.
  </Step>

  <Step title="Enable Webhooks">
    Toggle webhooks **On** and select your registered endpoint.
  </Step>

  <Step title="Select Events">
    Choose which events should trigger webhooks.
  </Step>

  <Step title="Add Custom Fields (Optional)">
    Add custom key-value pairs to include in every webhook payload.
  </Step>

  <Step title="Save Configuration">
    Click **Save** to activate webhooks for this VoiceFlow.
  </Step>
</Steps>

## Webhook Payload

When an event occurs, EolasFlow sends a POST request with this JSON structure:

```json theme={null}
{
  "event": "call.completed",
  "call_id": "CA1234567890abcdef",
  "workflow_id": "uuid-of-call-flow",
  "timestamp": "2024-01-15T14:30:00Z",
  "webhook_id": "unique-webhook-id",
  "idempotency_key": "unique-key-for-dedup",
  "customer": {
    "name": "John Smith",
    "phone": "+15551234567",
    "email": "john@example.com"
  },
  "call_data": {
    "duration_seconds": 180,
    "status": "completed",
    "recording_url": "https://...",
    "transcript": "Agent: Hello... Customer: Hi...",
    "summary": "Customer interested in product demo"
  },
  "custom_fields": {
    "your_field": "your_value"
  }
}
```

## Authentication Options

### Bearer Token

Your token is sent in the Authorization header:

```
Authorization: Bearer your-token-here
```

### API Key Header

Your API key is sent in a custom header:

```
X-API-Key: your-api-key
```

### Signing Secret (HMAC-SHA256)

When you configure a signing secret, EolasFlow includes a signature header:

```
X-Webhook-Signature: sha256=abc123...
```

Verify the signature on your server:

```python theme={null}
import hmac
import hashlib

def verify_signature(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)
```

## Retry Logic

If your endpoint returns an error (non-2xx status), EolasFlow automatically retries:

* **Max Retries:** 3 attempts
* **Initial Delay:** 5 seconds
* **Backoff:** Exponential (5s, 10s, 20s)

<Note>
  To prevent duplicate processing, use the `idempotency_key` field to identify duplicate webhook deliveries.
</Note>

## Monitoring Webhooks

### View Webhook Logs

1. Go to **VoiceFlows** → open your VoiceFlow → **Webhooks**
2. Click the **Logs** tab
3. View execution history with status, timing, and response data

### Filter Logs

Filter webhook logs by:

* Event type
* Success/failure status
* Date range
* Specific call

### Resend a Webhook

If a webhook failed and you've fixed the issue:

1. Find the failed webhook in the logs
2. Click **Resend**
3. The webhook is re-sent with the original payload

## Testing Webhooks

### Test Endpoint Connectivity

Before using a webhook endpoint:

1. Go to **Connections → Webhooks**
2. Click **Test** on your endpoint
3. Verify the test request succeeds

### Send Test Webhook from VoiceFlow

1. Go to **VoiceFlow settings → Webhooks tab**
2. Click **Send Test Webhook**
3. A sample payload is sent to your endpoint

## Best Practices

<Tip>
  **Respond Quickly:** Return a 2xx response within 30 seconds. Do heavy processing asynchronously.
</Tip>

<Tip>
  **Use Signing Secrets:** Verify webhook authenticity to prevent spoofing.
</Tip>

<Tip>
  **Handle Duplicates:** Use the `idempotency_key` to detect and ignore duplicate deliveries.
</Tip>

<Tip>
  **Log Everything:** Keep logs of received webhooks for debugging.
</Tip>

<Warning>
  **Secure Your Endpoint:** Validate signatures, use HTTPS, and implement rate limiting.
</Warning>

## Common Use Cases

| Use Case                       | Events to Subscribe                |
| ------------------------------ | ---------------------------------- |
| **Update CRM after call**      | `call.completed`                   |
| **Real-time dashboard**        | All events                         |
| **Trigger follow-up workflow** | `call.completed`, `call.voicemail` |
| **Alert on failures**          | `call.failed`                      |
| **Track call outcomes**        | `call.completed`                   |

## Troubleshooting

### Webhooks Not Arriving

1. Check that webhooks are enabled on the VoiceFlow
2. Verify the endpoint URL is correct and accessible
3. Check your server logs for incoming requests
4. Review webhook logs for error messages

### Authentication Failures

1. Verify your token/API key is correct
2. Check the header name matches your server's expectations
3. Ensure your server is checking the right header

### Timeouts

If webhooks are timing out:

* Reduce processing time in your webhook handler
* Process asynchronously and return 200 immediately
* Increase timeout in endpoint settings (max 120 seconds)

## Build Your Own Workflows

Want to connect EolasFlow to any tool of your choice? Use automation platforms like **n8n**, **Zapier**, or **Make** to create custom webhook endpoints.

<CardGroup cols={3}>
  <Card title="n8n" icon="circle-nodes">
    Self-hosted, open-source automation
  </Card>

  <Card title="Zapier" icon="bolt">
    5000+ app integrations
  </Card>

  <Card title="Make" icon="wand-magic-sparkles">
    Visual workflow builder
  </Card>
</CardGroup>

With these tools you can:

* Send call data to any CRM (Salesforce, HubSpot, Pipedrive, etc.)
* Trigger Slack/Teams notifications
* Update Google Sheets or databases
* Send automated follow-up emails
* Connect to any API or service

<Card title="Automation Workflows Guide" icon="rocket" href="/guides/automation">
  Learn how to build custom integrations with n8n, Zapier, and more
</Card>

## Next Steps

<CardGroup cols={2}>
  <Card title="MCP Integration" icon="plug" href="/guides/mcp">
    Give your agents access to external tools during calls
  </Card>

  <Card title="View Call Logs" icon="phone" href="/guides/calls">
    Review calls that triggered webhooks
  </Card>
</CardGroup>