Custom Actions

Build custom AI actions with webhooks

Custom Actions#

Create custom actions that let your AI agent interact with your own systems.

How It Works#

1. You define an action (name, description, parameters)
2. Agent learns when to use it
3. When triggered, agent calls your webhook
4. Your system processes and returns result
5. Agent uses result in response

Creating a Custom Action#

Step 1: Define the Action#

Go to AI Actions → Custom → Create Action

Step 2: Define Parameters#

What information the agent should collect:

{
  "type": "object",
  "properties": {
    "customer_email": {
      "type": "string",
      "description": "Customer's email address"
    },
    "order_number": {
      "type": "string",
      "description": "Order number to look up"
    }
  },
  "required": ["order_number"]
}

Step 3: Configure Webhook#

Your endpoint receives:

{
  "action": "check_order_status",
  "parameters": {
    "order_number": "ORD-12345"
  },
  "context": {
    "agent_id": "...",
    "conversation_id": "...",
    "contact_id": "..."
  }
}

Your endpoint returns:

{
  "success": true,
  "result": {
    "status": "shipped",
    "tracking_number": "1Z999AA10123456784",
    "estimated_delivery": "January 20, 2024"
  }
}

Example: Order Lookup#

Action Setup#

• Name: check_order_status
• Description: "Check the status of a customer order"
• Parameters: order_number (required)

Conversation#

User: "Where's my order? Order number is ORD-12345"

Agent: calls check_order_status webhook

Agent: "Your order ORD-12345 has shipped! Tracking number is 1Z999AA10123456784, with an estimated delivery of January 20th."

Security#

Authentication#

Add authentication to your webhook:

• API key in header
• Signature verification
• IP allowlisting

SSRF Protection#

AlonChat validates webhook URLs:

• No localhost
• No private IPs
• HTTPS required

Error Handling#

If your webhook fails:

{
  "success": false,
  "error": "Order not found"
}

Agent responds appropriately:

"I couldn't find that order number. Could you double-check it?"

Best Practices#

1. Fast responses - Keep under 5 seconds
2. Clear descriptions - Help agent know when to use
3. Validate input - Check parameters before processing
4. Return useful data - Give agent what it needs to respond
5. Handle errors - Return clear error messages