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

# Inbound Webhooks

> Receive JSON data from external systems to find or create contacts, update custom fields, and trigger automated actions in ChatbotX.

**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](https://mintcdn.com/chatbotx/dHddCrlyPo0xda94/images/inbound_webhooks_tools_card.png?fit=max\&auto=format\&n=dHddCrlyPo0xda94\&q=85\&s=eb7f9036e1ad518b6ae13c62ac37eeb6)

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:

| Feature | Location | Direction | Common Use Cases |
| - | - | - | - |
| **Inbound Webhooks** | **Tools > Inbound Webhooks** | External systems → ChatbotX | Lead capture from website forms, new order alerts from Shopify/WooCommerce, payment confirmations, and contact syncing from external CRMs. |
| **Outbound Webhooks** | **Triggers > Webhooks** | ChatbotX → External systems | Sending contact details to external CRM, notifying inventory systems when an order tag is applied, or triggering external fulfillment. |
| **External API Request** | **Flow Builder (Action Node)** | Bidirectional (Sync) | Querying live order status, fetching real-time exchange rates, or validating coupon codes during an active chat conversation. |

## 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:

```mermaid theme={null}
graph TD
    A["1. Inbound JSON Request"] --> B["2. Route to Target Inbox"]
    B --> C["3. Identify or Create Contact"]
    C --> D["4. Save Incoming Data to Fields"]
    D --> E["5. Execute 'After Saving Data' Actions"]
```

## 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](https://mintcdn.com/chatbotx/dHddCrlyPo0xda94/images/inbound_webhooks_dashboard_list.png?fit=max\&auto=format\&n=dHddCrlyPo0xda94\&q=85\&s=de2eb8e889782b87890c7814f806f476)

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](https://mintcdn.com/chatbotx/dHddCrlyPo0xda94/images/inbound_webhooks_url_and_sample_json.png?fit=max\&auto=format\&n=dHddCrlyPo0xda94\&q=85\&s=7f616ed462fd47357dea3ecf4cea191a)

Webhook URL configuration and formatted sample JSON payload

> [!NOTE]
>
> 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](https://mintcdn.com/chatbotx/dHddCrlyPo0xda94/images/inbound_webhooks_find_or_create_contact.png?fit=max\&auto=format\&n=dHddCrlyPo0xda94\&q=85\&s=6a0cd112c82ffdfb4a676afbf1c15690)

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](https://mintcdn.com/chatbotx/dHddCrlyPo0xda94/images/inbound_webhooks_browse_contact_modal.png?fit=max\&auto=format\&n=dHddCrlyPo0xda94\&q=85\&s=6772771239f526a3dd8b4ce2cd906ebb)

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](https://mintcdn.com/chatbotx/dHddCrlyPo0xda94/images/inbound_webhooks_save_incoming_data.png?fit=max\&auto=format\&n=dHddCrlyPo0xda94\&q=85\&s=ed202f8a8dee14b861f44fa1a234ed25)

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](https://mintcdn.com/chatbotx/dHddCrlyPo0xda94/images/inbound_webhooks_browse_mapping_modal.png?fit=max\&auto=format\&n=dHddCrlyPo0xda94\&q=85\&s=400897204c6d450cfd86fdd9ece42dbd)

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

> [!TIP]
>
> 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](https://mintcdn.com/chatbotx/dHddCrlyPo0xda94/images/inbound_webhooks_after_saving_data.png?fit=max\&auto=format\&n=dHddCrlyPo0xda94\&q=85\&s=a4e020f8f47370211c6d4ba99191265c)

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.

> [!WARNING]
>
> 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:

```text theme={null}
https://app.chatbotx.io/api/hooks/{unique_token}
```

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.

> [!WARNING]
>
> 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](https://mintcdn.com/chatbotx/dHddCrlyPo0xda94/images/inbound_webhooks_analytics_view.png?fit=max\&auto=format\&n=dHddCrlyPo0xda94\&q=85\&s=2d392da86dde7335c93f4017c799cf39)

Inbound Webhooks analytics view displaying request count and delivery logs

## JSONPath Syntax Reference

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

| Syntax Type | Example Expression | Description |
| - | - | - |
| **Standard Dot Notation** | `$.customer.phone` | Accesses the `phone` property inside the `customer` object. |
| **Nested Array Index** | `$.order.items[0].name` | Accesses the `name` of the first item in the `items` array. |
| **Bracket Notation** | `$["customer-data"]["email"]` | Accesses properties containing hyphens, spaces, or special characters. |
| **Deeply Nested Field** | `$.order.shipping.address.city` | Traverses multiple hierarchical objects. |

## Frequently Asked Questions

> [accordion] Do I need to configure both an email address and a phone number?
>
> 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.

> [accordion] What happens if the contact does not exist in ChatbotX yet?
>
> 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.

> [accordion] Can the flow triggered by 'Start Another Flow' use the incoming data?
>
> 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}}`.

> [accordion] Can I create multiple Inbound Webhooks for different services?
>
> 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.

> [accordion] How do I troubleshoot if data is not being saved?
>
> 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.