Triggers & Events

The lead capture trigger is the most common way webhooks fire in Chattlebot. When a visitor submits their information through the chatbot — their email, name, phone number, or any other captured data — all webhooks with the Lead Capture trigger enabled will fire automatically. This happens concurrently, not sequentially, so if you have three webhooks listening for lead captures (say, one to Zapier, one to your CRM, and one to Slack), all three fire at the same time. Configuration is simple: toggle the 'Trigger on Lead Capture' switch to enabled. Optionally, set an urgency filter to only fire for specific urgency levels — Low, Medium, or High. For example, you might only want to notify your Slack channel about high-urgency leads while still sending all leads to your CRM. The urgency level is determined by Chattlebot's AI analysis of the conversation.

The workflow trigger fires a webhook as a step in an automation workflow. Instead of firing automatically on events, the webhook is called explicitly at a specific point in your workflow using the action format 'execute_webhook:{webhookId}'. This gives you precise control over when the webhook runs and what data it receives. When used in a workflow, all workflow variables are available in the webhook payload template — not just lead data, but any data collected or computed in earlier workflow steps. After the webhook executes, response data is extracted and made available to subsequent workflow steps with a webhook_' prefix. For example, if your webhook returns a JSON response with a 'status' field, the next workflow step can access it as 'webhook_status'. This makes workflows powerful for multi-step automations: capture a lead, enrich the data via webhook, then route based on the enriched result.

The AI tool trigger fires when the AI chatbot decides it needs real-time data during a conversation. This is fundamentally different from other triggers — instead of you defining when the webhook runs, the AI decides based on what the user is asking. To enable this, set 'ai_callable' to true on the webhook and configure a tool name, description, and parameters. When a chat starts, the AI loads all available AI-callable webhooks as tools in its toolbox. When a user asks a question that requires real-time information — like product availability, appointment slots, or order status — the AI evaluates its available tools, picks the right one, collects the required parameters from the conversation, and fires the webhook. The response data flows back to the AI, which uses it to answer the user in natural language. For the full configuration guide, including how to write effective AI descriptions, define parameters, and set up response filtering, see the AI-Callable Webhooks guide.

The manual test trigger is for setup and debugging — it lets you fire a webhook on demand to verify everything works before going live. Click the 'Send Test Webhook' button in the webhook editor to send a test request. Chattlebot generates sample data that mirrors a real lead capture: a test email address, sample name, demo phone number, default urgency and sentiment values, a mock conversation transcript, and current timestamps. The test result shows you the HTTP status code, response body, and execution time. In the execution history, test fires are logged with 'triggered_by: test' so you can easily distinguish them from real triggers. Use manual tests whenever you change the webhook URL, modify the payload template, update authentication credentials, or want to verify the receiving endpoint is working correctly.

A single webhook can have multiple triggers enabled simultaneously. The most common combination is Lead Capture + AI-Callable — the same webhook fires both when a lead is captured and when the AI needs data during a chat. However, combining triggers requires careful consideration. When a webhook has both lead capture and AI-callable triggers enabled, your endpoint may receive the same lead's data multiple times: once from the lead capture event and potentially again from an AI tool call during the same conversation. To handle this safely, design your endpoints to be idempotent — meaning processing the same data twice produces the same result. Use upsert logic (update if exists, create if new) rather than blind inserts. For example, if your CRM endpoint uses the lead's email as a unique key and upserts the contact record, duplicate calls won't create duplicate contacts. Another approach is to check the 'triggered_by' field in the payload to distinguish between trigger types and handle each appropriately.