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

# Webhooks configuration

> Set up inbound and outbound webhooks in Thoughtly to trigger agents, push call events to external systems, and integrate any API without a prebuilt connector.

export const NextSection = ({title, icon, href, description}) => <div>
		<br />
		<Card title={title} icon={icon} href={href} horizontal="true">
			{description}
		</Card>
	</div>;

Set up custom webhooks to integrate Thoughtly with any external system that supports HTTP API calls, enabling flexible automation and data synchronization.

<Note>
  **New to Integrations?** Check out [Native Integrations](/integrations/getting-started) first for pre-built connections with popular platforms like HubSpot, Salesforce, and Calendly.
</Note>

<Tip>
  **Webhook Success Tips**

  * **Start Simple**: Begin with basic webhook configurations before adding complexity
  * **Test Thoroughly**: Validate both success and failure scenarios
  * **Monitor Performance**: Track webhook response times and success rates
  * **Plan for Scale**: Design endpoints to handle your expected call volume
  * **Document Integration**: Maintain clear documentation for your webhook implementations
</Tip>

## Understanding Webhooks in Thoughtly

Unlike [native integrations](/integrations/getting-started), webhooks in Thoughtly are **not configured globally**. Instead, they are set up at the point of use within:

* **[Automations](/automations/getting-started)**: Use **Thoughtly -> On Call Completed** for post-call workflows, and add webhook steps when you need to push data to external systems
* **[Agent Builder](/agents/overview)**: Real-time webhooks for mid-call actions and live data updates

This architecture provides maximum flexibility for different use cases while maintaining clear separation between automation and real-time integration needs.

## Webhook Configuration Locations

### In Automations

In [automations](/automations/getting-started), webhooks are typically used in two ways:

1. **Send data out** as a step (for example, start with **Thoughtly -> On Call Completed**, then add a **Send Webhook** step to push call results to your CRM or database).

2. **Start an automation** from an external system using the **Webhook -> Incoming Webhook** trigger.

3. **Navigate** to **Tools → Automations** in the primary navigation

4. **Create or edit** an automation workflow

5. **Add webhook action** within the automation builder

6. **Configure** endpoint URL, headers, and payload

**Use Cases for Automation Webhooks**:

* Updating CRM records after call completion (see [native CRM integrations](/integrations/getting-started))
* Triggering follow-up emails or SMS campaigns
* Syncing call outcomes with business intelligence systems
* Creating tasks or tickets in project management tools

<Tip>
  For post-call workflows, prefer **Thoughtly -> On Call Completed**. You can scope the trigger to **one agent, multiple agents, or All Agents**, and then optionally send results to external systems via a webhook step.
</Tip>

### In Agent Builder (Mid-call Actions)

Webhooks in the [Agent Builder](/agents/overview) enable real-time interactions during active phone calls:

1. **Open** Agent Builder for your target agent
2. **Navigate** to Mid-call [Actions](/agents/actions) section
3. **Add webhook action** within the agent's workflow
4. **Configure** real-time endpoint and response handling

**Use Cases for Mid-call Webhooks**:

* Looking up customer information during calls
* Updating external systems with live call data
* Triggering real-time notifications to support teams
* Retrieving dynamic pricing or inventory information

## Webhook Configuration Elements

### Essential Configuration

**Endpoint URL**: The target URL where Thoughtly will send HTTP requests
**HTTP Method**: Typically POST for data submission
**Headers**: Authentication tokens, content-type, and custom headers
**Payload**: JSON data structure sent to your endpoint

### Authentication Options

**API Key Authentication**:

```json theme={null}
Headers: {
  "Authorization": "Bearer YOUR_API_KEY",
  "Content-Type": "application/json"
}
```

**Custom Authentication**:
Configure custom headers and authentication schemes as required by your endpoint

### Payload Structure

Thoughtly sends structured JSON payloads containing:

* **Call Information**: Call ID, duration, participants, outcome
* **Agent Data**: Agent ID, agent name, [assigned phone number](/phone-number/getting-started)
* **Transcript**: Structured array of conversation turns (see below)
* **Custom Fields**: Any additional data configured in your [automation](/automations/getting-started) or [agent](/agents/overview)

**Transcript structure:** The transcript is provided as a structured array of objects, not a plain string. Each entry includes:

* `transcript` - The spoken content
* `speaker` - Either `"ai"` or `"user"`
* `createdAt` - ISO 8601 timestamp when the message was created
* `step` - (AI messages only) The step number in the conversation
* `node_id` - (AI messages only) The node ID from the agent builder

**Example transcript:**

```json theme={null}
[
  {
    "transcript": "Hello, how can I help you today?",
    "speaker": "ai",
    "createdAt": "2025-11-03T19:33:18.330Z",
    "step": 1,
    "node_id": "node_abc123"
  },
  {
    "transcript": "I'd like to schedule an appointment",
    "speaker": "user",
    "createdAt": "2025-11-03T19:33:25.120Z"
  }
]
```

## Webhook Development Guidelines

### Endpoint Requirements

**Response Time**: Design endpoints for quick responses (\< 5 seconds recommended)
**HTTP Status Codes**: Return appropriate status codes (200 for success, 4xx for client errors)
**Error Handling**: Implement proper error responses for debugging

### Security Best Practices

<Warning>
  **Secure Your Webhooks**

  * **HTTPS Only**: Always use HTTPS endpoints for secure data transmission
  * **Authentication**: Implement proper API key or token-based authentication
  * **Input Validation**: Validate all incoming webhook data before processing
</Warning>

### Payload Processing

**JSON Parsing**: Ensure robust JSON parsing with error handling
**Data Validation**: Verify required fields exist before processing
**Idempotency**: Design endpoints to handle duplicate webhook calls gracefully

## Testing and Validation

### Initial Setup Testing

1. **Configure** webhook with test endpoint
2. **Trigger** the automation or agent action
3. **Verify** payload delivery and format
4. **Confirm** your endpoint receives and processes data correctly

## Error Handling and Monitoring

### Monitoring Recommendations

**Logging**: Maintain logs of all webhook calls and responses
**Alerting**: Set up monitoring for webhook failures or slow responses
**Health Checks**: Regular endpoint availability testing

## Common Use Cases

### CRM Synchronization

**Automation Webhook**: Update customer records after each call

```json theme={null}
{
  "call_id": "CALL_001",
  "customer_phone": "+1555-012-1234",
  "agent_id": "AGENT_001",
  "call_outcome": "qualified_lead",
  "duration_seconds": 180
}
```

### Real-time Data Retrieval

**Mid-call Webhook**: Fetch customer information during calls

```json theme={null}
{
  "action": "customer_lookup",
  "phone_number": "+1555-012-1234",
  "agent_id": "AGENT_001",
  "call_id": "CALL_001"
}
```

### Notification Systems

**Automation Webhook**: Alert teams about important call outcomes

```json theme={null}
{
  "alert_type": "high_priority_lead",
  "customer_data": {...},
  "agent_notes": "Customer interested in enterprise package",
  "follow_up_required": true
}
```

<Note>
  **Performance Considerations**

  * **Latency Impact**: Mid-call webhooks can affect call quality if endpoints are slow
  * **Concurrent Calls**: Ensure your endpoints can handle multiple simultaneous requests
  * **Rate Limiting**: Consider implementing rate limiting for high-volume scenarios
</Note>

## Expected Results

After successful webhook configuration:

**For Automations**:

* Webhooks trigger automatically after configured call events
* External systems receive structured call data
* Business processes update based on call outcomes

**For Mid-call Actions**:

* Real-time data exchange during active calls
* Dynamic agent responses based on external data
* Live updates to external systems during conversations

<Note>
  **No Automatic Retries**

  Thoughtly does not implement automatic retry policies for failed webhook deliveries. Design your integration to handle:

  * **Network Failures**: Temporary connection issues
  * **Endpoint Downtime**: Service availability problems
  * **Authentication Errors**: Token expiration or invalid credentials
</Note>

## Advanced: Triggering Automations with Webhooks

You can also trigger Thoughtly automations from external systems using webhook triggers. This allows you to start Voice Agent calls or run automations based on events in your other tools.

For more information, see:

* [Trigger Automation with Webhook](/api-reference/webhooks/trigger-automation-with-webhook)
* [Automation Triggers](/automations/triggers)

<Warning>
  **Current Limitations**

  * **No automatic retries** for failed webhook deliveries
  * **No built-in webhook delivery logging** in Thoughtly interface
  * **Configuration required per automation/agent** (no global webhook settings)
</Warning>

## See Also

* [Native Integrations](/integrations/getting-started) - Pre-built integrations with popular platforms
* [Automations Overview](/automations/getting-started) - Learn about automation workflows
* [Agent Actions](/agents/actions) - Configure mid-call actions in agents
* [Automation Actions](/automations/actions) - Available actions for automations
* [Automation Triggers](/automations/triggers) - Trigger automations with webhooks

<NextSection title="View All Integrations" icon="grid" href="/integrations/getting-started" description="Explore all available native integrations ->" />

## Rate-limit retries

If a webhook endpoint returns `429`, Thoughtly retries once after the `Retry-After` delay when supported. Keep `Retry-After` values reasonable and design your endpoint to be idempotent so a retry does not create duplicate side effects.

## Webhook-compatible automation triggers

The automation webhook endpoint only executes automations that have webhook-compatible triggers. This protects automations that are meant to run on schedules, calls, or other internal events from being triggered externally.