Custom API Actions

Let your agent call your own API during a conversation — look up orders, check accounts, trigger your backend.

Custom API Actions#

A Custom API Action lets your AI agent call your own backend during a conversation. When a customer asks for something only your systems know — an order status, an account balance, a reservation — the agent calls your HTTPS endpoint with the details it collected and uses the response in its reply.

Create one under Automations → Create custom action.

Note: This is different from project API Keys. Custom API Actions are outbound calls your agent makes to your API during a chat. API Keys are for external apps calling AlonChat.

How It Works#

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

Creating a Custom API Action#

Step 1: Define the Action#

FieldDescription
NameInternal identifier (e.g., check_order_status)
Display NameHuman-readable name shown in the dashboard
DescriptionWhen the agent should use this action — be specific
Webhook URLYour HTTPS endpoint

Tip: The description is critical — the AI uses it to decide when to trigger the action.

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 the agent should collect before calling your webhook:

json
{
  "type": "object",
  "properties": {
    "order_number": {
      "type": "string",
      "description": "Order number to look up (e.g., ORD-12345)"
    }
  },
  "required": ["order_number"]
}

The agent asks the customer for any required parameter it doesn't already have from the conversation.

Step 3: Configure the Webhook#

Request — your endpoint receives a POST with this JSON body:

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

Response — return JSON the agent can use:

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

The agent turns the result object into a natural-language reply.

Timeouts#

Custom action webhooks have a request timeout. If your endpoint doesn't respond in time, the action is treated as failed and the agent tells the customer it couldn't complete the request. For long-running work, return an immediate acknowledgment and notify the customer later.

Security#

Authentication#

Protect your endpoint with one or more of:

  • API key in header that your endpoint validates
  • Signature verification to confirm the request came from AlonChat
  • IP allowlisting

SSRF Protection#

AlonChat validates every webhook URL:

  • HTTPS required — only secure endpoints are allowed
  • No localhost — localhost / 127.0.0.1 are rejected
  • No private IPs — private ranges (10.x.x.x, 192.168.x.x, etc.) are rejected

Error Handling#

Return a failure response when something goes wrong:

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

The agent handles it gracefully:

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

Best Practices#

  1. Fast responses — customers are waiting in real time.
  2. Clear descriptions — so the agent knows exactly when to use the action.
  3. Validate input on your end before processing.
  4. Return useful data — the more context in result, the better the reply.
  5. Use HTTPS and design endpoints to be idempotent in case of retries.

Related Pages#