Webhook Response Block - Send Custom HTTP Responses to Webhook Callers

Overview

The Webhook Response Block lets you send a custom HTTP response back to whatever system called your Webhook Block. Without this block, ChatMaxima replies with a generic 200 OK and a body of {"status":"success"}. That is fine for most callbacks, but some integrations expect a specific shape, status code, or content type before they consider the delivery successful.

Use the Webhook Response Block when the caller is strict about the reply: payment gateways that retry unless they see a particular JSON field, legacy SOAP systems that expect XML, iPaaS tools that parse the response into subsequent steps, or form builders that display the reply to the user.

Webhook Block vs Webhook Response Block

Aspect	Webhook Block	Webhook Response Block
Direction	Receives inbound HTTP call	Sends HTTP response back to the caller
Placement	First block or mid-flow	Anywhere downstream of a Webhook Block
Required	Yes (to accept external calls)	Optional (a default 200 OK is sent if omitted)
Purpose	Trigger or resume the flow	Shape the HTTP reply to the caller

Where to Find It

1. Open your chatbot in Studio
2. Drag the Webhook Response block from the left sidebar onto the canvas
3. Connect it downstream of the Webhook block that received the request
4. Double-click the block to configure it

The Webhook Response block does not need to be the immediate next block. You can place Condition, API, Set Variable, and Message blocks between the Webhook block and the Webhook Response block. When the response block is reached during flow execution, its configuration becomes the HTTP reply to the original caller.

Configuration

Step 1: Set the HTTP Status Code

Status Code	Use When
200	Default. Indicates success to most callers
201	Useful when the webhook created a resource (e.g. a new conversation)
202	Accepted for async processing (the bot will act on it later)
400	Reject malformed payloads
401	Reject unauthorized callers
500	Indicate a bot-side failure for retry logic

Step 2: Set the Content-Type

Content-Type	Use When
application/json	Most modern integrations (default)
application/xml	Legacy SOAP-style callers
text/plain	Health-check style callbacks
text/html	Form submission acknowledgements displayed to a user

Step 3: Write the Response Body

The body is a free-form text field. Write the exact payload you want returned to the caller. Variables captured earlier in the flow can be inserted with {variable_name} syntax (single curly braces).

For JSON:

{
  "received": true,
  "conversation_id": "{conversation_id}",
  "lead_id": "{reference_id}",
  "acknowledged_at": "{current_time}"
}

For XML:

<response>
  <status>success</status>
  <conversation_id>{conversation_id}</conversation_id>
</response>

For plain text:

OK

Step 4: Submit and Save

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

How It Works

External system POSTs to webhook URL
                 │
                 ▼
       Webhook Block fires
                 │
                 ▼
   (Optional) intermediate blocks:
   - Condition to validate payload
   - API Block to enrich data
   - Set Variable to compute fields
                 │
                 ▼
    Webhook Response Block reached
                 │
                 ▼
    Custom HTTP response returned
    to the original caller
                 │
                 ▼
    Flow continues to downstream blocks
    (messages, further logic, etc.)

The HTTP response is sent synchronously: the external caller stays connected until the response block is reached. Because of this, keep the path between the Webhook block and the Webhook Response block fast. Avoid long-running API calls or time-consuming logic before the response block, otherwise the caller may time out.

Common Use Cases

Acknowledge with Conversation ID

An iPaaS tool (n8n, Zapier, Make) wants to record the conversation ID in its own system after triggering the webhook.

• Status Code: 201
• Content-Type: application/json
• Body:

{
  "created": true,
  "conversation_id": "{conversation_id}",
  "reference_id": "{reference_id}"
}

Echo Back Validation Result

A form builder posts user input. The bot validates it and returns a pass/fail so the form can show the right message.

• Status Code: 200
• Content-Type: application/json
• Body:

{
  "valid": true,
  "message": "Your request has been received"
}

Reject Invalid Payloads

Combine a Condition block (checking required fields) with a Webhook Response block on the failure branch that returns 400.

• Status Code: 400
• Content-Type: application/json
• Body:

{
  "error": "missing_required_field",
  "field": "{missing_field}"
}

Payment Gateway Confirmation

A payment gateway posts a settle webhook. The bot has to return a specific JSON shape or the gateway will keep retrying.

• Status Code: 200
• Content-Type: application/json
• Body:

{
  "status": "acknowledged",
  "transaction_id": "{transaction_id}"
}

SMS Delivery Receipt

A legacy SMS provider expects a plain text OK response.

• Status Code: 200
• Content-Type: text/plain
• Body: OK

Best Practices

• Keep the path short. Only place blocks between the Webhook and Webhook Response if they run fast. Long API calls should go after the response block so the caller does not time out
• Always return quickly for retrying callers. Payment gateways and SMS providers often retry within seconds. Reaching the response block within a second or two avoids duplicate notifications
• Match the caller's expected shape exactly. Strict callers reject responses even when the status code is correct. Read the integration docs and test with their sample requests
• Use Condition blocks to branch the response. Have one Webhook Response block on the success branch and a different one (with 400 or 401) on the failure branch
• Include the conversation or reference ID. This makes it easy to correlate the caller's logs with the conversation in ChatMaxima
• Do not put sensitive data in the response. The response is visible to the caller. Only return what they need to confirm receipt

Troubleshooting

Caller receives the default 200 OK instead of my custom response

1. Confirm a Webhook Response block is present and reachable from the Webhook block
2. Check the flow graph: if a Condition routes around the response block, the default is used
3. Make sure the block was saved. Click Submit in the modal, then Save Changes on the top bar

Caller retries repeatedly

1. Ensure the status code matches what the caller considers success. Some providers only accept 200, not 201 or 202
2. Verify the response body matches the caller's expected shape. Inspect their docs or logs
3. Check for upstream blocks between the Webhook and Webhook Response that are slow. The caller may be timing out before the response is sent

Variables appear as raw {variable_name} in the response body

1. Confirm the variable was set by an earlier block in the same flow
2. Variable names are case-sensitive. Check spelling
3. For nested fields, use dot notation: {customer.email}, not {customer_email}
4. If the variable is from the inbound webhook payload, make sure the payload actually contained the field

Malformed JSON is rejected by strict callers

1. Validate the body template as JSON before saving. An unquoted variable in a string field will produce invalid JSON if the value contains quotes or line breaks
2. For numeric fields like {amount}, do not wrap in quotes. For string fields, always wrap: "name": "{name}"
3. Test with a sample call (using curl or Postman) to see the actual bytes returned

Content-Type mismatch

1. Some callers require application/json; charset=utf-8 explicitly. The default sends application/json without the charset
2. SOAP clients may require text/xml rather than application/xml. Check the integration docs

Next Steps

• Webhook Block - Receive inbound HTTP calls to trigger or resume a flow
• API Block - Call external APIs from the flow
• Studio Overview - Explore all block types and flow builder features