Custom Webhooks

Custom webhooks are for when you need to connect to your own API, an internal service, or a platform that isn't covered by the Zapier, n8n, or Make templates. With custom webhooks, you have full control over every aspect of the HTTP request: the URL, method, headers, payload format, and authentication. Common use cases include sending leads to your own backend API, integrating with industry-specific CRMs, connecting to self-hosted tools, or calling any REST API that accepts HTTP requests.

In your Chattlebot dashboard, navigate to your bot's Actions page and click 'Custom Webhooks' → 'Add Webhook'. Select the 'Custom Webhook' template from the template picker. This gives you a blank canvas with all settings unlocked. Enter a descriptive name for your webhook and paste your endpoint URL — this is the URL of the API or service you want to send data to. The URL can include query parameters if your API requires them.

Select the HTTP method that matches what your API expects. POST is the most common choice — it sends the lead data in the request body. Use GET when you need to fetch data (the payload is sent as query parameters). PUT replaces an entire resource — useful for full-record updates in your CRM. PATCH performs a partial update — only the fields you include are modified. DELETE removes a resource — rarely used for webhooks but available for cleanup workflows. If you're unsure, POST is almost always the right choice.

If your API requires authentication, select the appropriate type from the dropdown. Chattlebot supports four authentication methods: None — no credentials sent (use for endpoints that rely on URL-based security, like Zapier catch hooks). Basic — sends a username and password encoded as Base64 in the Authorization header. Bearer Token — sends a token in the Authorization header as 'Bearer {your_token}' (common for OAuth2 APIs and JWT-based services). API Key — sends a custom header (like X-API-Key) with your key value (common for third-party API platforms). See the Authentication guide for detailed setup instructions for each type.

The payload template defines the JSON body sent with each webhook request. The default template includes all available lead and conversation variables, but you can modify it to match your API's expected format. Use {{variable}} syntax to insert dynamic values — for example, {{lead.email}} inserts the lead's email address. You can nest variables inside custom JSON structures, rename fields, add static values, and remove fields you don't need. Common variables include lead.email, lead.name, lead.phone, lead.urgency, lead.category, lead.sentiment, conversation.summary, and bot.name. See the Payload Reference guide for the complete list of available variables.

Custom headers let you include additional metadata with your webhook request. Content-Type is set to 'application/json' by default. Add custom headers when your API requires them — common examples include API versioning headers (like X-API-Version), content negotiation headers, tracking headers (like X-Source to identify the request came from Chattlebot), or correlation IDs for request tracing. Click 'Add Header' to include a new header with a name and value pair. Variables ({{...}}) can be used in header values too.

Response mapping lets you extract specific values from the API's response for use in workflows or as data the AI can reference. Add a mapping by specifying a JSONPath expression (like $.id or $.data.status) to target a specific field in the response, and a variable name to store the extracted value. You can also set a default value that's used when the field is missing from the response. This is especially useful when chaining webhooks in workflows — the extracted values become available as variables prefixed with 'webhook_' in subsequent steps. See the Response Mapping guide for advanced JSONPath examples and patterns.

Click 'Send Test Webhook' to send sample data to your endpoint. The test results will show the HTTP status code, response body, and execution time. Verify that: the connection succeeds (200 OK or your API's expected success code), the authentication is accepted (no 401 or 403 errors), the response format is what you expect, and any response mappings correctly extract the fields you configured. If everything looks good, enable the webhook using the toggle. Your custom webhook is now live and will fire according to the triggers you've configured. Monitor the webhook's health dashboard for ongoing success rates and any errors.