Webhooks
Connect your agents to external services via HTTP: outbound webhooks your agents call, and inbound endpoints that trigger an agent.
Objective
Connect your agents to external services over HTTP. The Webhooks module has two tabs:
- Outbound — actions your agents call (POST to a CRM, look up an order, create a ticket).
- Inbound — endpoints that external systems call to trigger an agent (from n8n, Make, Zapier, or any REST API).
Access
Sidebar -> Webhooks Route: /app/{tenant}/webhooks
Roles
- owner, admin only.
- The
agentrole sees the sidebar item but gets an "Access denied" banner: only owners and admins can manage webhooks.
Prerequisites
- A verified email (required to create a webhook).
- Webhook count is limited by your plan.
Outbound webhooks
Outbound webhooks are actions an agent can call during a conversation. Click Create Webhook.
Endpoint
| Field | Notes |
|---|---|
| Name | Shown to the agent as the action name. |
| Description | Tells the agent when to use it. |
| Method | GET, POST, PUT, PATCH, DELETE, or HEAD (default POST). |
| API URL | The endpoint. May contain {variables} the agent fills in. |
Authentication
- None
- Bearer token
- Basic (user + password)
- API Key (value + parameter name, default X-API-Key, sent as a header or query)
- OAuth 2.0 (client credentials): token URL, client id, client secret, scope, and where credentials go (body or basic)
Credentials are encrypted. When you edit a webhook, leave a secret field blank to keep the current value.
Request options
- Sign outbound requests: add an HMAC signature. Generate and copy the signing secret (shown once).
- Timeout: a slider from 1 to 30 seconds.
- Headers and Query Params: key/value rows.
- Parameters: a visual builder (Name / Type: string, number, integer, boolean / Description / Required), toggleable to a raw JSON editor. These are the values the agent supplies at call time.
- Body Template: key/value rows or raw JSON, with a body encoding selector (JSON or form).
- Response handling: a Response path to extract a field from the JSON response, and Success codes that count as success.
The {variable} placeholders can appear in the URL, headers, query params, and body; the agent fills them in when it calls the webhook.
Test
- Inside the modal, fill sample values for each {placeholder} and run a test — you see the HTTP status, duration, and response body.
- Each saved webhook card has a Test button (disabled with a tooltip when the URL still contains {variables}).
- Recent runs appear as execution logs (method, status, duration, response or error, and time).
Inbound webhooks
Inbound webhooks let an external system trigger an agent by POSTing to a per-agent endpoint at {origin}/api/inbound/{token}. Switch to the Inbound tab and click New inbound webhook.
| Field | Notes |
|---|---|
| Instruction | Natural language describing what the agent should do when the endpoint is hit. |
| Name | A label for the endpoint. |
| Agent | The agent that runs. |
| Auth type | HMAC signature, Bearer token, or None (not recommended). |
| Delivery channel | No delivery (tools only), WhatsApp, or Email — offered only if the chosen agent can deliver on it. |
| Destination | The WhatsApp number or email to deliver to, when a delivery channel is chosen. |
After you create or regenerate an endpoint, a reveal-once panel shows the endpoint URL, the plaintext secret (only once), and a ready-to-run curl snippet. Copy the secret now — it is not shown again.
Each inbound endpoint card has an active/paused switch, Regenerate secret, Edit, and Delete, a last-triggered indicator, and an expandable Recent events log (status: success, auth_failed, rate_limited, inactive, error; source IP; payload excerpt). Inbound endpoints are limited by your plan.
Good practices
- Give outbound webhooks a clear Name and Description so the agent knows exactly when to call them.
- Use the Test flow before relying on a webhook in production.
- Prefer HMAC or Bearer auth for inbound endpoints; avoid None.
- Keep secrets safe: they are shown only once. Regenerate if a secret leaks.