Custom Actions

Build custom AI actions with webhooks to connect your agent to any external system

Custom Actions#

Create custom actions that let your AI agent interact with your own systems. When a customer asks your agent to do something that requires your backend, a custom action calls your webhook endpoint with the relevant data.

How It Works#

1. You define an action (name, description, parameters)
2. Agent learns when to use it based on the description you provide
3. When triggered, agent calls your webhook with collected parameters
4. Your system processes the request and returns a result
5. Agent uses the result in its response to the customer

Creating a Custom Action#

Step 1: Define the Action#

Go to Actions and click Create custom action

Tip: The description is critical. The AI uses it to decide when to trigger the action. Be explicit about what the action does and when it should be used.

Good description:

"Check the status of a customer's order. Use when the customer asks about their order status, delivery tracking, or where their package is. Requires the order number."

Vague description:

"Order lookup"

Step 2: Define Parameters#

Specify what information the agent should collect from the customer before calling your webhook:

{
  "type": "object",
  "properties": {
    "customer_email": {
      "type": "string",
      "description": "Customer's email address"
    },
    "order_number": {
      "type": "string",
      "description": "Order number to look up (e.g., ORD-12345)"
    }
  },
  "required": ["order_number"]
}

The agent will ask the customer for any required parameters it does not already have from the conversation.

Step 3: Configure Webhook#

Request format:

Your endpoint receives a POST request with this JSON body:

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

Response format:

Your endpoint should return JSON:

{
  "success": true,
  "result": {
    "status": "shipped",
    "tracking_number": "1Z999AA10123456784",
    "estimated_delivery": "March 25, 2026"
  }
}

The agent uses the result object to compose a natural-language response to the customer.

Example: Order Lookup#

Action Setup#

• Name: check_order_status
• Description: "Check the status of a customer order. Use when the customer asks about order status, shipping, or delivery tracking. Requires order number."
• Parameters: order_number (required), customer_email (optional)

Conversation#

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

Agent: (calls check_order_status webhook)

Agent: "Your order ORD-12345 has shipped! The tracking number is
       1Z999AA10123456784 and the estimated delivery is March 25th."

Timeout Limits#

Custom action webhooks have a timeout of 30 seconds. If your endpoint does not respond within 30 seconds, the action is considered failed and the agent will inform the customer that the action could not be completed.

For long-running operations, consider:

• Starting the operation and returning an immediate acknowledgment
• Having the customer check back later
• Using webhooks to notify when the operation completes

Security#

Authentication#

Protect your webhook endpoint. Recommended approaches:

• API key in header: Include a secret key that your endpoint validates
• Signature verification: Verify the request signature to confirm it came from AlonChat
• IP allowlisting: Restrict access to AlonChat's IP ranges

SSRF Protection#

AlonChat validates all webhook URLs to prevent server-side request forgery:

• No localhost: URLs pointing to localhost or 127.0.0.1 are rejected
• No private IPs: URLs pointing to private network ranges (10.x.x.x, 192.168.x.x, etc.) are rejected
• HTTPS required: Only HTTPS endpoints are allowed

Error Handling#

If your webhook encounters an error, return a failure response:

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

The agent handles errors gracefully:

Agent: "I couldn't find that order number. Could you double-check it
       and try again?"

If your endpoint returns an HTTP error status (4xx, 5xx) or times out, the agent will inform the customer that the action could not be completed and suggest alternatives.

Best Practices#

1. Fast responses -- Keep webhook processing under 5 seconds when possible. Customers are waiting in real time.
2. Clear descriptions -- Write detailed action descriptions so the agent knows exactly when to use your action.
3. Validate input -- Always validate parameters on your end before processing.
4. Return useful data -- Include all the information the agent needs to give a complete response. The more context in the result, the better the agent's reply.
5. Handle errors gracefully -- Return clear, customer-friendly error messages.
6. Use HTTPS -- Always use HTTPS endpoints for security.
7. Idempotent operations -- Design your endpoints to handle duplicate calls safely, in case of retries.

Next Steps#

• Actions Overview -- See all built-in actions
• Webhooks -- Set up event-based webhooks
• API Reference -- Full API documentation