Webhook Block - Receive Inbound HTTP Calls in Your Chatbot Flow

Overview

The Webhook Block lets an external system call your chatbot over HTTP. It can be used in two ways: as the first block of a flow (the webhook itself starts the conversation), or as a mid-flow block that pauses the conversation and waits for an external callback to resume it. In both cases, the incoming payload is parsed and made available to downstream blocks as variables. You can optionally send a custom HTTP response back to the caller using the Webhook Response Block.

This is the inverse of the API Block. The API Block sends outbound requests. The Webhook Block listens for inbound requests. Typical use cases include starting a new conversation from an external event (a form submission, a CRM record creation, an iPaaS trigger like n8n or Zapier), waiting for a payment gateway callback, receiving OTP delivery confirmation from a third-party SMS provider, getting notified when a long-running backend job completes, or accepting async updates from an external app.

Webhook Block vs API Block

Aspect	API Block	Webhook Block
Direction	Outbound (bot calls API)	Inbound (external system calls bot)
Trigger	Automatic when flow reaches block	External HTTP POST starts or resumes the flow
Placement	Mid-flow only	First block or mid-flow
Wait Behavior	Synchronous, 30 second timeout	Starts flow on arrival, or pauses flow until call arrives
Typical Use	Look up data, push updates	Start conversations from external events, wait for async callbacks
Response Handling	Parses response body into variables	Incoming payload becomes variables

Where to Find It

1. Open your chatbot in Studio
2. Drag the Webhook block from the left sidebar onto the canvas
3. Place it as the first block of your flow (to start a conversation from an external event) or connect it after any previous block (to pause and wait for a callback mid-flow)
4. Double-click the block to configure it

To send a custom HTTP response back to the caller, add a Webhook Response block immediately after the Webhook block.

Webhook as the First Block

When the Webhook block is the first block of the flow, there is no active conversation yet. The external POST creates the conversation, parses the payload into variables, and starts the flow from the very beginning. This is the pattern to use when:

• A new lead is created in your CRM and you want the bot to reach out
• A form is submitted on your website and you want the bot to follow up
• An n8n, Zapier, or Make workflow triggers a new chat session
• A backend event (order placed, support ticket opened) should kick off a bot conversation

Webhook Mid-Flow

When the Webhook block is placed after another block, the flow pauses at that point until the external POST arrives. This is the pattern to use when you need to hand off to an external system, wait for its async response, and then continue the flow based on what it returned.

How It Works

First-Block Mode

External system POSTs to webhook URL
                 │
                 ▼
   New conversation is created
                 │
                 ▼
   Payload parsed into variables
                 │
                 ▼
   Flow starts from the next block
                 │
                 ▼
   Webhook Response sent (optional)

Mid-Flow Mode

Bot flow runs ──▶ Reaches Webhook Block ──▶ Flow pauses
                                                  │
                             External system POSTs to webhook URL
                                                  │
                                                  ▼
                            Payload parsed into variables
                                                  │
                                                  ▼
                     Webhook Response sent (optional)
                                                  │
                                                  ▼
                     Flow continues to next block

In mid-flow mode, the bot stores the current block position when it pauses. When the external POST arrives at the webhook URL, the system matches it to the paused conversation, resumes from that block, and continues downstream.

Configuration

Step 1: Place the Webhook Block in the Flow

Drag the block onto the canvas at the point where the flow should start from or wait for an external event. For example:

• As the first block, to let a CRM, form, or iPaaS tool start a new chat conversation
• After capturing payment details, to wait for payment gateway confirmation
• After triggering a backend job via an API block, to wait for the job-complete notification

Step 2: Copy the Webhook URL

Each Webhook block exposes a unique URL shown in the block configuration. The format is:

https://chatmaxima.com/webhooks/chatbot/<bot_token>/<block_id>/

Pass this URL to the external system as the destination for its POST request. For iPaaS tools (n8n, Zapier, Make) you paste it into the HTTP step. For CRMs and form builders, configure it as an outgoing webhook in their dashboard. For payment gateways and async backends, set it as the callback URL when you kick off the work.

Step 3: Authenticate the Caller

The webhook URL accepts a Bearer token in the Authorization header. Use the token shown in the block configuration so the webhook only accepts calls from systems you trust.

curl -X POST https://chatmaxima.com/webhooks/chatbot/<bot_token>/<block_id>/ \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your_token>' \
  --data '{
    "type": "Conversation",
    "channel": "",
    "account_alias": "",
    "reference_id": "",
    "data": {
      "name": ""
    }
  }'

Payload Shape

Field	Purpose
type	Event type, typically Conversation to start or resume a chat
channel	Channel the conversation should use (e.g. whatsapp, website). Leave empty to use the default
account_alias	Team alias when the bot is shared across multiple accounts
reference_id	External identifier you can use to tie the conversation back to a record in your system
data	Object containing any fields you want to pass in as variables (e.g. name, email, phone, custom fields)

Step 4: Reference Incoming Payload Fields

When the POST arrives, the data object is parsed and each field becomes a variable available to all downstream blocks.

For a payload like:

{
  "type": "Conversation",
  "channel": "whatsapp",
  "reference_id": "ORDER-9981",
  "data": {
    "name": "Priya",
    "phone": "+919000000000",
    "order_id": "ORDER-9981",
    "customer": {
      "email": "priya@example.com"
    }
  }
}

You can reference:

• {name} for Priya
• {phone} for +919000000000
• {order_id} for ORDER-9981
• {customer.email} for nested fields
• {reference_id} for top-level metadata

Step 5: Submit and Save

Click Submit in the block modal, then save the flow using Save Changes in the top bar.

Webhook Response Block

Pair the Webhook block with a Webhook Response Block when the caller expects a specific HTTP response. Without the response block, the bot returns a default 200 OK with {"status":"success"}.

The Webhook Response Block lets you customize the status code (e.g. 201, 400, 500), content type (application/json, application/xml, text/plain, text/html), and response body sent back to the caller. You can insert flow variables with {variable_name} syntax.

Common patterns:

• Return 201 Created with the new {conversation_id} for iPaaS tools
• Return 400 with an error field when the payload is invalid
• Return text/plain OK for SMS delivery callbacks
• Return XML for legacy SOAP integrations

See the full Webhook Response Block documentation for configuration options, examples, and troubleshooting.

Best Practices

• Always validate incoming payloads. Use a Condition block after the Webhook block to verify fields like status == "success" before proceeding
• Use the Webhook Response block when the caller (payment gateway, SMS provider, etc.) expects a specific acknowledgement format. Without it, the caller gets a generic 200 OK
• Set a meaningful timeout elsewhere. The Webhook block itself does not time out, so combine it with Inactivity Timeout to avoid flows that stay paused indefinitely
• Secure the webhook URL. The token in the URL is unique per conversation. Do not expose the URL publicly or log it in systems the user can read
• Handle the failure case. Branch the flow based on the incoming payload. If the external event indicates failure, send a recovery message or route to an agent

Common Use Cases

CRM Lead Creates a Conversation (First-Block)

A new lead is added in your CRM, and the bot opens a WhatsApp conversation to qualify them.

1. Webhook Block (first block): CRM POSTs lead payload with phone, name, source
2. Message Block: Hi {name}, thanks for your interest!
3. Question Block: Ask qualifying questions
4. API Block: Push qualified data back to the CRM

n8n or Zapier Trigger (First-Block)

An automation tool fires a webhook when a specific event happens (new Shopify order, Typeform submission, etc.), and the bot follows up with the customer.

1. Webhook Block (first block): n8n POSTs {"phone":"...", "order_id":"..."}
2. Message Block: Your order {order_id} has shipped!

Payment Gateway Callback

User initiates payment, bot sends them to a payment page, then waits for the gateway to POST the result.

1. API Block: Create payment session, store payment_url
2. Message Block: Send payment_url to user
3. Webhook Block: Pause flow, pass the webhook URL to the gateway as the callback
4. Condition Block: Branch on {status} == "success"
5. Webhook Response Block: Return {"received":true} to the gateway

Async Job Notification

Bot triggers a long-running report generation job, waits for completion, then sends the report link to the user.

1. API Block: Submit job, store job_id, include webhook URL as callback
2. Message Block: "Generating your report, this may take a minute..."
3. Webhook Block: Wait for job-done callback
4. Message Block: Your report is ready: {report_url}

Third-Party OTP Delivery Status

Bot sends an OTP via an external SMS provider that uses webhooks to confirm delivery.

1. API Block: Trigger OTP send, pass webhook URL
2. Webhook Block: Wait for delivery status
3. Condition Block: Branch on {delivery_status}
4. Message Block: Ask for the OTP code or apologize for delivery failure

External Form Submission

A separate web app collects extra info and POSTs it to the bot when the user finishes.

1. Message Block: Send form URL to user
2. Webhook Block: Wait for form submission
3. Message Block: Thanks, we received your {form_field}

Troubleshooting

Flow is stuck on the Webhook block (mid-flow)

1. Confirm the external system actually POSTed to the webhook URL. Check their delivery logs
2. Verify the URL is reachable from the external system (not blocked by firewall or IP allowlist)
3. Make sure the URL includes the full path and the trailing token
4. Combine with Inactivity Timeout to auto-close conversations that never receive the callback

First-block webhook is not starting a conversation

1. Confirm the Webhook block is the very first block in the flow (no other block connects into it)
2. Verify the payload includes a recipient identifier (phone, email, or visitor ID) that the bot can use to create the conversation
3. Check the bot is published and the channel (WhatsApp, website widget, etc.) is connected
4. Inspect the response status returned to the caller. A 4xx indicates the payload was rejected

Incoming payload fields are empty in downstream blocks

1. Confirm the Content-Type of the incoming POST is application/json or a supported form type
2. Check the exact field names in the payload. Variable names are case-sensitive
3. For nested fields, use dot notation: {customer.email}, not {customer_email}
4. Inspect the raw incoming payload in the conversation log to see what was actually received

Caller gets a generic 200 OK instead of my custom response

1. Make sure you added a Webhook Response block after the Webhook block
2. Verify the response block is reachable in the flow graph. A Condition block may be routing around it
3. Double-check the Submit button was clicked and the flow was saved

External system rejects the webhook response

1. Confirm the Content-Type matches what the caller expects (for example, application/json vs text/plain)
2. Validate the response body is well-formed. An unclosed JSON object will cause strict callers to retry
3. Check the HTTP status code. Some callers only accept 200, not 201 or 202

Multiple POSTs arrive for the same conversation

Some external systems retry webhooks if they think the first delivery failed. The webhook URL is idempotent per conversation, so only the first valid POST resumes the flow. Subsequent POSTs receive the configured response without advancing the flow again.

Next Steps

• Webhook Response Block - Send custom HTTP responses back to the caller
• API Block - Call external APIs from the flow
• Inactivity Timeout - Auto-close conversations that stay paused too long
• Conversation End Block - Manually end conversations with a restart button
• Studio Overview - Explore all block types and flow builder features