Webhook

The Webhook integration allows the assistant to make HTTP requests to any external API during the conversation. It is the most flexible integration in the platform.

Basic Configuration

json

{
  "type": "WEBHOOK",
  "url": "https://api.yoursite.com/endpoint",
  "method": "POST",
  "headers": [
    { "key": "Authorization", "value": "Bearer my_token" },
    { "key": "Content-Type", "value": "application/json" }
  ],
  "body": {
    "field": "value"
  },
  "responseDirective": "If the status is 'success', confirm to the user. If 'error', ask them to try again."
}

Supported HTTP Methods

GET · POST · PUT · DELETE

Available Variables

Use $variableName in URLs, headers, and body. Variables are substituted automatically before the request.

System Variables

Variable	Value
`$session.id`	Unique session UUID
`$company.id`	Company ID on the platform
`$assistant.id`	Configured assistant ID

ClientData Variables

Any key sent via client_data when creating or updating the session:

bash

# Session with customer data
curl -X PUT /session/{id} \
  -F 'client_data={"user_id":"usr_999","plan":"enterprise"}'

In the webhook: $user_id, $plan

Trigger Argument Variables

Parameters that the LLM extracted from the conversation (defined in the trigger's JSON Schema):

json

// Trigger defined with parameter "order_number"
// In the webhook: $order_number
{
  "url": "https://api.store.com/orders/$order_number/status",
  "method": "GET"
}

Image Variables

When the user sends images in the conversation:

Variable	Value
`$images[0]`	URL of the 1st image
`$images[1]`	URL of the 2nd image
`$images`	JSON array with all URLs

Practical Examples

Check order status

json

{
  "url": "https://erp.company.com/api/orders/$order_number",
  "method": "GET",
  "headers": [
    { "key": "Authorization", "value": "Bearer $erp_token" }
  ],
  "responseDirective": "Inform the customer of the order status clearly. If the status is 'delivered', congratulate them. If 'in_transit', provide the estimated delivery."
}

Create support ticket

json

{
  "url": "https://helpdesk.company.com/api/tickets",
  "method": "POST",
  "headers": [
    { "key": "Authorization", "value": "Bearer $helpdesk_api_key" },
    { "key": "X-Session-ID", "value": "$session.id" }
  ],
  "body": {
    "title": "$issue_title",
    "description": "$issue_description",
    "priority": "$priority",
    "customer": {
      "name": "$customer_name",
      "email": "$customer_email"
    },
    "origin": {
      "channel": "whatsapp",
      "session": "$session.id",
      "company": "$company.id"
    }
  },
  "responseDirective": "Confirm the created ticket number to the customer and say our team will get in touch within 24h."
}

Analyze image sent by user

json

{
  "url": "https://api.vision.company.com/analyze",
  "method": "POST",
  "headers": [
    { "key": "Authorization", "value": "Bearer $vision_api_key" }
  ],
  "body": {
    "image_url": "$images[0]",
    "all_images": $images,
    "session_ref": "$session.id"
  },
  "responseDirective": "Describe what was identified in the image in a way that's useful for the user."
}

`responseDirective`

The responseDirective is an instruction for the LLM on how to interpret and use the webhook's response when formulating the reply to the user.

json

"responseDirective": "If the 'available' field is true, offer the time slots from the 'slots' list. If false, inform there is no availability and ask if they want to be notified."

When not specified, the LLM uses the webhook response as additional context and freely decides what to communicate.

If InterpretResponse is set to false on the trigger, responseDirective is ignored.

Updating ClientData via Response

Your webhook can return data that becomes available in the session for subsequent calls:

json

// Return from your webhook
{
  "status": "success",
  "patient_id": "pat_12345",
  "session": {
    "client_data": {
      "patient_id": "pat_12345",
      "patient_name": "Ana Smith",
      "last_appointment": "2025-02-15"
    }
  }
}

Values in session.client_data are automatically merged into the session. $patient_id will be available in subsequent webhooks.

Variable Substitution Behavior

Ordered by length

Variables are substituted from longest to shortest name. This avoids partial substitutions:

Variables: $session_id (10 chars) and $session (7 chars)
Text: "Session: $session_id: company: $session.company"

Correct: substitutes $session_id first (longer name)
Wrong would be: substituting $session first, generating partial "$session_id"

Automatic encoding

Context	Treatment
URL path (`/orders/$id`)	URL-encoded (`%20`, `%2F`, etc.)
URL query params (`?q=$search`)	URL-encoded
Headers	Literal substitution
JSON body (strings)	JSON-escaped (`\n`, `\"`, etc.)

Debug and Errors

The result of each webhook call is logged in the session logs with:

HTTP response status
Response body
Variables used
Execution time

Logs are available at Dashboard → Conversations → Session → Logs.