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

# Webhooks

> Connect your AI apps to automation platforms and external services

## What are Webhooks?

<Info>
  Webhooks enable real-time communication between your CalStudio AI apps and external services. When specific events occur in your app, webhooks automatically send data to your chosen destination, powering instant automations and integrations.
</Info>

Webhooks are essential for:

* **Automation Platforms**: Integrate with Zapier, Make.com, or custom workflows
* **CRM Integration**: Sync conversations to Salesforce, HubSpot, or other systems
* **Analytics**: Send chat data to your data warehouse or analytics tools
* **Notifications**: Alert your team about important conversations
* **Custom Workflows**: Trigger any action based on user interactions

## Setting Up Webhooks

### Step 1: Create Your Webhook Endpoint

First, create a webhook endpoint in your automation platform:

<Tabs>
  <Tab title="Zapier">
    1. Create a new Zap
    2. Choose **"Webhooks by Zapier"** as trigger
    3. Select **"Catch Hook"**
    4. Copy the webhook URL provided
  </Tab>

  <Tab title="Make.com">
    1. Create a new scenario
    2. Add **"Webhooks"** module
    3. Select **"Custom webhook"**
    4. Copy the webhook URL
  </Tab>

  <Tab title="Custom API">
    1. Create an endpoint that accepts POST requests
    2. Ensure it can handle JSON payloads
    3. Return a 200 status code on success
  </Tab>
</Tabs>

### Step 2: Configure in CalStudio

1. **Navigate to your app settings**
   * Open your AI app in the CalStudio dashboard
   * Go to the **"Webhooks"** section

2. **Add your webhook URL**
   * Paste the URL from your automation platform
   * CalStudio will validate the URL format

3. **Select trigger events**

   Choose when to send webhook notifications:

   <CardGroup cols={2}>
     <Card title="Message Sent" icon="message">
       Triggers when a user sends a message to your AI app
     </Card>

     <Card title="New User Signup" icon="user-plus">
       Triggers when a new user registers or starts using your app
     </Card>

     <Card title="Custom Conditions" icon="code-branch">
       Define custom logic using natural language prompts
     </Card>

     <Card title="Conversation End" icon="stop">
       Triggers when a conversation session ends
     </Card>
   </CardGroup>

### Step 3: Configure Custom Conditions (Optional)

For advanced use cases, create custom triggers:

1. **Select "Custom Conditions"**
2. **Write a trigger prompt** that describes when to fire the webhook
3. **CalStudio will evaluate** each conversation against your conditions

**Example prompts:**

* "When a user asks about pricing or costs"
* "If the user expresses frustration or dissatisfaction"
* "When the user provides their email address"
* "If the conversation mentions a competitor"

## Webhook Payload Structure

CalStudio sends a POST request with a JSON payload containing event details:

<CodeGroup>
  ```json Sample Webhook Request theme={null}
  {
    "event": "Message sent",
    "timestamp": "2024-01-01T12:00:00.000Z",
    "app_name": "My App",
    "user_email": "user@example.com",
    "user_name": "John Doe",
    "last_message": "User message",
    "response": "App response message"
  }
  ```
</CodeGroup>

### Payload Fields

| Field          | Type   | Description                                                         |
| -------------- | ------ | ------------------------------------------------------------------- |
| `event`        | string | The type of event that triggered the webhook ("Message sent", etc.) |
| `timestamp`    | string | The exact time the event occurred, formatted as ISO 8601            |
| `app_name`     | string | The name of your CalStudio app                                      |
| `user_email`   | string | The user's email address                                            |
| `user_name`    | string | The user's display name                                             |
| `last_message` | string | The most recent message sent by the user                            |
| `response`     | string | The AI app's response to the user                                   |

## Common Use Cases

<CardGroup cols={2}>
  <Card title="Lead Capture" icon="user-plus">
    Send qualified leads to your CRM when users express interest
  </Card>

  <Card title="Support Escalation" icon="headset">
    Create tickets in Zendesk when users report issues
  </Card>

  <Card title="Analytics Tracking" icon="chart-line">
    Log conversations to Google Analytics or Mixpanel
  </Card>

  <Card title="Email Follow-up" icon="envelope">
    Trigger personalized emails based on conversation topics
  </Card>
</CardGroup>

## Example: Zapier Integration

Here's a step-by-step example of connecting CalStudio to Google Sheets via Zapier:

<Steps>
  <Step title="Create a Zap">
    1. Log in to Zapier and create a new Zap
    2. Search for "Webhooks by Zapier" as the trigger
    3. Choose "Catch Hook" as the trigger event
    4. Copy the custom webhook URL
  </Step>

  <Step title="Configure CalStudio">
    1. Go to your app's webhook settings
    2. Paste the Zapier webhook URL
    3. Select "Message Sent" as the trigger
    4. Save your configuration
  </Step>

  <Step title="Test the Connection">
    1. Send a test message in your AI app
    2. Return to Zapier and click "Test trigger"
    3. Zapier should receive the webhook data
  </Step>

  <Step title="Add Google Sheets Action">
    1. Add a new action step
    2. Choose Google Sheets
    3. Select "Create Spreadsheet Row"
    4. Map webhook fields to sheet columns
  </Step>
</Steps>

## Best Practices

<Steps>
  <Step title="Secure Your Endpoints">
    * Use HTTPS for all webhook URLs
    * Implement authentication tokens if needed
    * Validate incoming requests
  </Step>

  <Step title="Handle Errors Gracefully">
    * Return appropriate HTTP status codes
    * Log failed webhook attempts
    * Set up retry logic for failures
  </Step>

  <Step title="Process Asynchronously">
    * Acknowledge webhooks quickly (\< 3 seconds)
    * Process data in background jobs
    * Avoid blocking operations
  </Step>

  <Step title="Monitor Performance">
    * Track webhook delivery rates
    * Set up alerts for failures
    * Monitor response times
  </Step>
</Steps>

## Testing Webhooks

<Tip>
  Use tools like [webhook.site](https://webhook.site) or [RequestBin](https://requestbin.com) to test your webhook configuration before connecting to production systems.
</Tip>

1. Create a test webhook URL
2. Configure it in CalStudio
3. Trigger test events in your app
4. Verify the payload structure
5. Implement your automation logic

## Troubleshooting

<AccordionGroup>
  <Accordion title="Webhook not firing">
    * Verify the webhook URL is correct and accessible
    * Check that events are properly configured
    * Ensure your app is active and receiving messages
    * Test with a simple webhook receiver first
  </Accordion>

  <Accordion title="Receiving duplicate webhooks">
    * Implement idempotency using the conversation ID
    * Check if multiple webhook configurations exist
    * Verify your endpoint isn't triggering retries
  </Accordion>

  <Accordion title="Missing data in payload">
    * Some fields are only available for specific events
    * User data requires users to be logged in
    * Check your app's privacy settings
  </Accordion>

  <Accordion title="Webhook delays">
    * Webhooks are sent immediately after events
    * Network latency may cause small delays
    * Check your endpoint's response time
  </Accordion>
</AccordionGroup>

## Related Resources

<CardGroup cols={2}>
  <Card title="WhatsApp Integration" icon="whatsapp" href="/account/whatsApp-integration">
    Connect your AI apps to WhatsApp
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Programmatic webhook management
  </Card>
</CardGroup>