Connect the agent to external services via webhooks

Webhook Actions are one of IperChat’s skills. When enabled, you can define up to 10 custom actions — each is a small “tool” the agent can use during chat to call an external HTTPS endpoint.

For example, you can create a check_order_status action wired to a Zapier flow: when a user asks “where is my order #4521?”, the agent invokes the webhook with { "order_id": "4521" } and uses the response to reply to the user.

It works with any service reachable over HTTPS: Zapier, Make.com, n8n, your own REST APIs, serverless functions, etc.

Activation

From the ops panel:

1. Open “My Tenant” (side menu → Manage group).
2. Expand the “Skills” section.
3. Find Webhook Actions and enable the toggle (the skill is marked as Experimental). The related permissions — View webhooks and Manage webhooks (create, edit, delete actions) — are assigned automatically.

After activation, the “Webhooks” entry appears in the sidebar (Manage group): this is where actions are created and managed.

Creating a webhook action

On the Webhooks page click ”+ New action”. The form collects:

Name (identifier)

The action’s “technical name”. Only lowercase letters, digits, and underscores, must start with a letter (e.g. check_order_status, create_lead_in_crm). It becomes the name of the tool the agent sees — so pick something readable.

Description (for the agent)

A natural-language sentence explaining what the action does. The agent reads this text to decide when to invoke it, so write it with the model in mind: clear, specific, with implicit examples of use cases.

Example: “Check the shipment status of an order given its ID.”

Webhook URL

The endpoint to call. Must be HTTPS (plain HTTP is rejected), must not contain embedded credentials (user:pass@), and cannot point to private or reserved networks — there’s SSRF protection that also blocks DNS rebinding attempts at execution time.

HTTP method and timeout

• Method: POST (default, JSON payload in body) or GET (parameters converted to a query string).
• Timeout: 1 to 30 seconds, default 10. Beyond that, the action fails and the agent communicates it to the user.

Parameters (input for the agent)

The list of parameters the agent must collect and send to the webhook. For each:

• Name — field identifier (lowercase letters, digits, underscores).
• Type — string, number, integer, or boolean.
• Description — explains to the model what the field represents and how to fill it.
• Req. — if selected, the agent will explicitly ask the user for the value before invoking the action.

Under the hood, these parameters become a JSON Schema exposed to the LLM as the tool signature.

Custom headers (optional)

Key/value pairs to add to the HTTP request (e.g. Authorization: Bearer sk-...). They’re stored encrypted in Secret Manager and are no longer visible after saving: if you need to change them, you rewrite them.

Enabled

Toggle to activate/deactivate the action without deleting it. Disabled actions don’t appear among the agent’s tools.

Testing the action

On the Webhooks page every action has a “Test” button: it sends a test request to your endpoint (empty JSON payload for POST, no parameters for GET) with the configured headers. In the response you see the HTTP status and the first 500 characters of the body.

Useful for checking that URL, authentication, and reachability are correct before letting the agent use it.

How the agent uses actions

Every enabled action becomes a tool available to the LLM in chat. Behavior is governed by these rules:

• The agent decides autonomously if and when to invoke an action, based on the description and parameters.
• Waits for the response before continuing the conversation.
• Doesn’t invent data: only uses what the webhook returns.
• If the action fails, it informs the user clearly and politely.

Example conversation

Customer: Where is my order #4521? Agent: [invokes check_order_status with { "order_id": "4521" }] Agent: Your order is currently in transit, shipped yesterday from our New York warehouse. Delivery is expected tomorrow morning.

Response format

• If the webhook returns valid JSON, the agent receives it as a structured object.
• If it returns non-JSON text, the agent receives it as a string in response_text.
• The response body is capped at 50 KB: anything beyond is truncated.

Limits and safeguards

• Maximum 10 webhook actions per tenant.
• Maximum 10 webhook calls per single conversation — beyond that, the agent receives a rate-limit error.
• Timeout max 30 seconds per call.
• Response cap at 50 KB — if truncated, the response is explicitly marked.
• URL validation repeated at every execution (defense against DNS rebinding).
• Private networks always blocked — no way to point a webhook at localhost, 10.x.x.x, 192.168.x.x, cloud metadata endpoints, etc.

Operator permissions

The two permissions related to the skill are:

• View webhooks (webhooks:read) — sees the list of actions and their configurations (except headers, never exposed).
• Manage webhooks (webhooks:manage) — create, edit, delete, enable/disable, and run tests.

You can assign them to individual operators from the Operators → Permissions page.