Skip to main content
Inbound Webhooks allow external applications, such as websites, e-commerce platforms (Shopify, WooCommerce), CRMs, payment gateways, and custom backend services, to send real-time data directly into your ChatbotX workspace without requiring third-party middleware like Zapier or Make. When an external platform sends a JSON POST request to your unique ChatbotX Webhook URL, the system automatically looks up or creates the contact, writes the incoming data into designated contact fields, and runs configured follow-up actions (such as tagging contacts or triggering automated flows).
Inbound Webhooks Tools Card

Inbound Webhooks tool card in the Tools dashboard

​
Understanding Webhooks in ChatbotX

To select the right tool for your automation requirements, understand the distinction between the webhook mechanisms available in ChatbotX:

​
Core Mechanics and Requirements

​
1. Request Protocol

External systems must deliver a standard POST request with a JSON-formatted payload (Content-Type: application/json) to the designated webhook endpoint.

​
2. Contact Matching Logic (First Match Wins)

ChatbotX searches for an existing contact within the specified inbox using four fallback tiers in exact order:
  1. Channel User ID (e.g., Messenger PSID, WhatsApp Phone Number, or Telegram User ID)
  2. Phone Number (formatted in standard international E.164, e.g., +84901234567)
  3. Email Address (e.g., alex.johnson@example.com)
  4. Full Name (e.g., Alex Johnson)
If a matching record exists, ChatbotX updates that contact. If no match is found, ChatbotX automatically creates a new contact inside the designated inbox.

​
3. Execution Pipeline

When a webhook payload is received, ChatbotX executes operations in a deterministic sequence:

​
Step-by-Step Configuration Guide

1

Access Inbound Webhooks and create a webhook

From the left sidebar, navigate to Tools, then click the Inbound Webhooks card.On the Inbound Webhooks management dashboard, click the blue + Create Inbound webhook button in the upper-right corner.
Inbound Webhooks Dashboard List

Inbound Webhooks dashboard showing the list of webhooks and management options

Enter a descriptive name that reflects the integration’s purpose (for example, New Order Follow-up or Website Lead Capture).
2

Load and format sample JSON

Obtain an example payload from the external service you are connecting. Paste the raw JSON into the Sample JSON editor.Click Format JSON to validate syntax and clean up indentation, then click Load sample JSON.
Webhook URL and Sample JSON

Webhook URL configuration and formatted sample JSON payload

Loading a sample payload does not trigger an actual live request. It enables ChatbotX to parse the JSON schema so you can use the visual Browse selector instead of manually typing JSONPath strings.
3

Configure contact identification (Find or create contact)

In the Find or create contact card, select how incoming requests route to an inbox:
  • Specific inbox: Assigns all incoming requests to a fixed channel and inbox (for example, BotX AI · Messenger or WhatsApp Official).
  • From payload: Dynamically resolves the destination inbox ID from a JSONPath variable in the incoming request.
Find or Create Contact

Configuring inbox selection and contact lookup identifiers with live value previews

Fill in at least one lookup identifier. You can type the JSONPath directly or click Browse next to each field to open the visual selector modal:
Browse Contact Identifier Modal

Visual Browse modal showing parsed JSON hierarchy and live result preview

Within the Browse modal:
  • Use the search bar to locate specific keys, paths, or values.
  • Click any node in the tree structure to automatically populate the JSONPath.
  • Check the Result preview line to verify the extracted value (for example, Result: CUST-98241 or Result: +84901234567).
  • Click Use path to apply the path to your field configuration.
4

Map incoming values to contact fields (Save incoming data)

Under the Save incoming data section, map incoming data attributes to your ChatbotX system and custom contact fields:
Save Incoming Data

Mapping payload properties to contact fields with live preview results

For each mapping:
  1. Click + Add field.
  2. Under Contact field, select the target system field or custom field (for example, order_id, order_status, order_total, shipping_address, or tracking_code).
  3. Under JSON path, click Browse to choose the attribute from the sample payload, or type the path manually.
  4. Confirm that the extracted value displayed below the input matches your expected value.
Browse Mapping Modal

Browsing order details in the visual JSON hierarchy to map into custom fields

Ensure the data type of the destination custom field matches the incoming value (e.g., use a Number field for order totals, Text fields for IDs and addresses, and Date fields for timestamps).
5

Set up automated actions (After saving data)

Under the After saving data section, define what ChatbotX should do immediately after the contact record has been created or updated:
After Saving Data Actions

Configured automated actions executed immediately after data is saved

Click + Add Action to add one or more automated operations:
  • Add Tag: Applies tags to segment or label the contact (for example, hot-lead, new_order, or paid_customer).
  • Remove Tag: Removes outdated tags (for example, clearing an unpaid or abandoned_cart tag).
  • Set Custom Field: Updates a fixed value or timestamp in another custom field.
  • Clear Custom Field: Resets an existing custom field value to empty.
  • Start Another Flow: Triggers an automated conversational flow (such as an order confirmation flow or appointment reminder). The triggered flow can immediately reference the contact fields populated by this webhook.
  • Transfer Conversation to Human: Automatically flags the conversation for live agent takeover in Live Chat.
6

Save, activate, and integrate your webhook

Review your configurations and click Save at the bottom of the page.Toggle the Active switch in the upper-right corner to activate the webhook.
Before activating the webhook, ensure you have selected an inbox, configured at least one contact identifier, and added at least one data mapping.
Click Copy next to the Webhook URL field to copy your endpoint URL:
Paste this URL into your external service’s webhook configuration settings (e.g., Shopify Webhooks, WooCommerce Webhook settings, or CRM automation rules).

​
Security and Token Regeneration

The Webhook URL contains a private authentication token that authorizes data ingestion directly into your workspace.
  • Masking: The token is obscured by default. Click the eye icon to inspect the full URL.
  • Regeneration: If your webhook URL has been exposed or compromised, click Regenerate to invalidate the existing token and generate a new secure endpoint.
Regenerating a webhook URL immediately breaks any existing integrations sending data to the old URL. You must update the webhook URL in all external sending systems immediately.

​
Monitoring and Analytics

ChatbotX provides dedicated analytics for each inbound webhook to help monitor integration health:
  1. Click View analytics in the upper-right corner of the webhook editor, or select View analytics from the three-dot menu (...) on the Inbound Webhooks dashboard.
  2. The Analytics dashboard provides:
    • Total requests received: Cumulative count of all accepted webhook requests since creation (duplicates excluded).
    • Delivery logs: Timestamped logs of recent deliveries kept for the latest 30 days.
    • Refresh: Click Refresh to poll the latest inbound logs.
Inbound Webhooks Analytics View

Inbound Webhooks analytics view displaying request count and delivery logs

​
JSONPath Syntax Reference

ChatbotX supports standard JSONPath notation, including dot notation and bracket notation:

​
Frequently Asked Questions

No. You only need to configure at least one identifier among Channel user ID, Phone, Email, or Full name. The incoming webhook request must provide a valid value at the configured JSONPath.
ChatbotX automatically creates a new contact inside the designated inbox using the provided identifiers and saved contact fields, then runs the configured After saving data actions.
Yes. ChatbotX writes incoming payload values into the contact’s custom fields before running the flow. In your flow nodes, you can reference these values using standard variables like {{order_id}}, {{order_total}}, or {{shipping_address}}.
Yes. You can create separate webhooks for distinct platforms (such as one for Shopify Orders, one for Website Leads, and one for CRM syncs). Each webhook has its own URL, mapping rules, and post-save actions.
Open the webhook’s Analytics view to confirm that requests are being received by ChatbotX. Verify that the incoming JSON structure matches the sample JSON you loaded, and check that custom field types match the incoming data types.