Webhooks

Trigger your agents from any external system with inbound HTTP requests

Webhooks let you trigger an xpander agent from any system that can make an HTTP request, including automation platforms like Zapier, form submissions, CI/CD pipelines, or your own applications.

Every webhook-enabled agent gets its own public URL - a unique, unguessable address that runs only that agent. No API key, no proxy backend, so you can call it straight from a contact form, a landing page, or a no-code builder that cannot set custom headers.

Once set up, you can:

• Trigger an agent run from any inbound HTTP POST with a prompt or payload
• Call it directly from a browser or form builder, with no credential to hide
• Choose synchronous (wait for the agent’s response) or asynchronous (fire-and-forget) invocation
• Upload files (documents, images, audio) alongside the prompt
• Extract specific fields from the agent’s response instead of returning the full payload
• Map nested fields from the incoming payload to the agent’s input parameters
• Pass through MCP OAuth tokens to authenticate downstream skills

Pre-requisites: an agent - one you run through Claude Code, Codex or OpenCode, or one you assembled in Xpander Chat.

Enable Webhooks

1. Open the agent's Channels

   In Xpander Chat, open the agent’s settings with the gear icon. On the Channel row, click Configure. The Channels panel opens; make sure Developer access is on.

   
2. Generate the public URL

   Under Public webhook URL, click Generate public URL. The section then shows the URL to copy and Regenerate URL, which replaces it and stops the old one working at once. Anyone with this URL can POST to it and run this agent with no API key, so treat it like a password. The API endpoint above it is the keyed alternative for your backend, CI or the SDK; Open API keys manages the keys it needs.

3. Test it

   Send a POST to the URL with a prompt, as in the requests below, and check the reply. The run also appears in the agent’s conversation and in the Session Manager.

Make Requests

Every webhook request is a POST to your agent’s public URL. The secret in the path both authenticates the call and binds it to that one agent, so nothing else is required.

curl -X POST 'https://webhook.xpander.ai/wh_YOUR_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"prompt": "Summarize the latest support tickets"}'

Because there is no header to set, the same call works straight from a page:

await fetch("https://webhook.xpander.ai/wh_YOUR_SECRET", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ name, email, message }),
});

The URL is the credential. Anyone holding it can run that agent, so treat it like a password: keep it out of public repositories, and use Regenerate URL in the Channels tab if it leaks. Regenerating kills the old URL immediately, so update anything that calls it.

A public URL can invoke its own agent and nothing else - it grants no access to your account, your other agents, or any management API.

Calls to a public URL default to asynchronous and return {"status": "Started", "task_id": "..."}, because the typical caller is a browser that should not wait. Add ?asynchronous=false when you want the agent’s answer in the response.

Invoking with an API key

The original key-based form still works and is unchanged, which suits server-to-server callers that already hold an organization key:

curl -X POST 'https://webhook.xpander.ai/?agent_id=YOUR_AGENT_ID' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{"prompt": "Summarize the latest support tickets"}'

Parameter	Location	Description
agent_id	Query string or body	Your agent’s ID
x-api-key	Header or query string	Your organization API key

An organization API key is an organization-wide credential - never embed it in browser JavaScript or anywhere a visitor can read it. That is what the public URL is for.

Optional Parameters

Parameter	Type	Description
prompt	string	Text input for the agent
asynchronous	boolean	Return immediately without waiting (default: true on a public URL, false with an API key)
task_id	string	Continue an existing conversation thread. A new value starts a thread with that id. A task_id belongs to the agent that first used it. A synchronous call that sends it to another agent answers 409. An asynchronous call still answers with status Started, and the message does not run.
user_id	string	User identifier for tracking
user_email	string	User email for personalization
user_first_name	string	User’s first name
user_last_name	string	User’s last name
getter	string	Dot-notation path to extract from the response
json	boolean	Parse the result as JSON instead of returning a string
user_tokens	string (JSON)	Pre-authenticated MCP OAuth tokens (see below)
disable_attachment_injection	boolean	When true, uploaded files are not injected into the LLM context window. File URLs are still available to the agent’s skills, but the raw content is not prepended to the prompt. Useful when files are large or the agent’s skills handle file processing directly.

You can include any additional fields in your request body - they’re all passed to the agent as context.

When the same parameter appears in multiple places, query parameters take priority over body parameters, which take priority over defaults.

Choose Sync vs Async

Synchronous (default with an API key; on a public URL add ?asynchronous=false) - The request blocks until the agent finishes and returns the full result. Best for short tasks and interactive workflows.

{
  "id": "task-uuid",
  "agent_id": "your-agent-id",
  "status": "completed",
  "result": "The agent's response...",
  "created_at": "2026-01-29T00:40:46.161472+00:00",
  "finished_at": "2026-01-29T00:40:47.919145+00:00",
  "source": "webhook",
  "execution_attempts": 1
}

Asynchronous - Set asynchronous=true to return immediately. The agent processes in the background. Best for long-running tasks, file processing, or when you don’t need the result inline.

curl -X POST 'https://webhook.xpander.ai/wh_YOUR_SECRET?asynchronous=true' \
  -H 'Content-Type: application/json' \
  -d '{"prompt": "Generate the monthly report"}'

{"status": "Started", "task_id": "4f9c1e2a-..."}

Upload Files

Upload files using multipart/form-data. The agent automatically processes them - OCR for images, text extraction for PDFs, transcription for audio.

curl -X POST 'https://webhook.xpander.ai/wh_YOUR_SECRET' \
  --form 'files=@"/path/to/document.pdf"' \
  --form 'files=@"/path/to/image.png"'

Supported types: PDF, DOC, DOCX, TXT, XLS, XLSX, CSV, PNG, JPEG, GIF, WEBP, SVG, ZIP.

Files must be uploaded directly - URLs to external files are not supported. The webhook needs the actual file content.

For large batches (10+ files), use async mode and break uploads into batches of 5-10 files.

Uploaded files are stored on xpander and exposed to your agent through secure presigned URLs. Those URLs are scoped to your organization’s agents and remain valid for 30 days after upload. Your agent never handles download or storage logic directly.

Extract Data from Responses

Use the getter parameter to extract a specific field from the agent’s response using dot notation.

curl -X POST 'https://webhook.xpander.ai/wh_YOUR_SECRET?asynchronous=false&getter=result.summary' \
  -H 'Content-Type: application/json' \
  -d '{"prompt": "Analyze quarterly report"}'

Instead of the full response object, this returns just the extracted value:

"Q4 revenue increased 15%"

Map Dynamic Parameters

Use params_mapping as a query parameter to extract values from nested payload fields and map them to webhook parameters. This is especially useful for integrations with Telegram bots, WhatsApp, and other messaging platforms where identifiers are nested. With curl, keep -g so curl sends the braces as they are instead of treating them as a URL pattern.

curl -g -X POST 'https://webhook.xpander.ai/wh_YOUR_SECRET?params_mapping={"task_id":"message.chat.id","prompt":"message.text","user_email":"message.from.email"}' \
  -H 'Content-Type: application/json' \
  -d '{
    "message": {
      "chat": {"id": 123456789},
      "from": {"email": "[e-mail]"},
      "text": "Hello agent!"
    }
  }'

The mapping uses dot notation to navigate nested fields. It supports all standard parameters: task_id, user_id, user_email, user_first_name, user_last_name, prompt. A task_id belongs to the agent that first used it. Reusing it continues that thread. Sending it to another agent answers 409 on a synchronous call. On an asynchronous call, the message does not run.

Pass MCP OAuth Tokens

If your agent uses skills served over MCP with OAuth authentication, pass pre-authenticated user tokens via user_tokens to bypass the interactive OAuth flow during webhook execution.

curl -X POST 'https://webhook.xpander.ai/?agent_id=YOUR_AGENT_ID' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "prompt": "Check my calendar",
    "user_email": "[e-mail]",
    "user_tokens": {
      "mcp-graph-item-uuid-1": "user-access-token-abc123"
    }
  }'

To find the graph item IDs for those skills, call the Get Agent API and inspect graph.items for entries with type: "mcp".

Monitor Webhook Runs

Every webhook invocation creates a task visible in the Session Manager, exactly like any other agent run. You get the full execution trace: prompts, skill calls with request/response payloads, files processed, timing, and token usage. For details on reading execution traces, see Threads.

Handle Errors

Status	Response	Cause
400	{"detail": "agent_id is required"}	Missing agent_id (API-key form only)
401	{"detail": "API key not specified"}	Unknown, regenerated or revoked public URL - or, on the API-key form, a missing x-api-key
403	{"detail": "Invalid API key"}	Wrong API key. A public URL that was already generated keeps working while Developer access is switched off; Regenerate URL is what revokes it
409	{"detail": "... Conversation <task_id> belongs to agent <agent_id>. Send the message through that agent, or start a new conversation with this one. ..."}	Synchronous call only. The task_id belongs to another agent.
503	{"detail": "Public webhook lookup temporarily unavailable"}	Transient issue resolving the URL; retry

Next Steps

Scheduled Tasks

Run agents on a recurring schedule

Omni in your MCP client

Reach Omni and your organization’s agents from Claude Code, Cursor or Claude Desktop

Monitor Runs

The task record: messages, skill calls, approvals, files, tokens and cost