Webhooks

Connect your AI apps to automation platforms and external services

What are Webhooks?

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.

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:

Zapier

1. Create a new Zap
2. Choose “Webhooks by Zapier” as trigger
3. Select “Catch Hook”
4. Copy the webhook URL provided

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:

   Message Sent

   Triggers when a user sends a message to your AI app

   New User Signup

   Triggers when a new user registers or starts using your app

   Custom Conditions

   Define custom logic using natural language prompts

   Conversation End

   Triggers when a conversation session ends

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:

Sample Webhook Request

{
  "event": "Message sent",
  "timestamp": "2024-01-01T12:00:00.000Z",
  "app_name": "My App",
  "user_email": "[e-mail]",
  "user_name": "John Doe",
  "last_message": "User message",
  "response": "App response message"
}

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

Lead Capture

Send qualified leads to your CRM when users express interest

Support Escalation

Create tickets in Zendesk when users report issues

Analytics Tracking

Log conversations to Google Analytics or Mixpanel

Email Follow-up

Trigger personalized emails based on conversation topics

Example: Zapier Integration

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

1. 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
2. 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
3. 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
4. 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

Best Practices

1. Secure Your Endpoints

   • Use HTTPS for all webhook URLs
   • Implement authentication tokens if needed
   • Validate incoming requests
2. Handle Errors Gracefully

   • Return appropriate HTTP status codes
   • Log failed webhook attempts
   • Set up retry logic for failures
3. Process Asynchronously

   • Acknowledge webhooks quickly (< 3 seconds)
   • Process data in background jobs
   • Avoid blocking operations
4. Monitor Performance

   • Track webhook delivery rates
   • Set up alerts for failures
   • Monitor response times

Testing Webhooks

Use tools like webhook.site or RequestBin to test your webhook configuration before connecting to production systems.

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

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

Receiving duplicate webhooks

• Implement idempotency using the conversation ID
• Check if multiple webhook configurations exist
• Verify your endpoint isn’t triggering retries

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

Webhook delays

• Webhooks are sent immediately after events
• Network latency may cause small delays
• Check your endpoint’s response time

Related Resources

WhatsApp Integration

Connect your AI apps to WhatsApp

API Reference

Programmatic webhook management