Webhooks enable you to trigger xpander.ai agents from any external system that can make HTTP requests. Each agent has a unique webhook URL for programmatic interaction.

​
Accessing Your Webhook URL

Agent Builder Interface

To find your webhook URL:

  1. Navigate to your agent in the Agent Builder
  2. Click the “Webhook” option in the center of the graph view
  3. The Webhook Configuration panel will open, providing:
    • Ready-to-use code snippets
    • Configuration instructions
    • Testing capabilities
    • Webhook management options

Webhook Configuration Interface

​
Making Webhook Requests

​
Required Parameters

ParameterTypeDescription
agent_idstringThe unique identifier of your agent
source_node_idstringThe starting node ID in your agent’s workflow
x-api-keystringYour API key for authentication (header or query parameter)
asynchronousbooleanWhether to wait for completion (false) or return immediately (true)

​
Request Body Options

OptionTypeDescription
filesfileOne or more files to process (PDF, PNG, JPEG, GIF, WEBP)
promptstringA text prompt to send to the agent

When uploading files, you must send the actual files using multipart/form-data. Direct external URLs to files are not supported as inputs. The platform will generate secure presigned URLs for your agent to access the uploaded files.

​
Content Types

  • With files: Use multipart/form-data (curl handles this automatically with --form)
  • JSON only: Use application/json with the appropriate header

​
File Handling

​
Supported File Types

xpander.ai supports a variety of file formats:

  • Documents: PDF
  • Images: PNG, JPEG, GIF, WEBP

​
Uploading Multiple Files

To process multiple files in a single request:

curl --location "https://webhook.xpander.ai?asynchronous=true" \
--header "x-api-key: YOUR_API_KEY" \
--form "prompt=Process these documents" \
--form "files=@/path/to/first-file.pdf" \
--form "files=@/path/to/second-file.pdf" \
--form "files=@/path/to/image.png" \
--form "source_node_id=YOUR_SOURCE_NODE_ID" \
--form "agent_id=YOUR_AGENT_ID"

For large batches of files (10+ files), we recommend:

  1. Using asynchronous mode (asynchronous=true)
  2. Breaking uploads into multiple requests of 5-10 files each
  3. Using a dedicated file uploader with retry capabilities

​
File URL Mechanism

When you upload files through the webhook:

  1. xpander.ai automatically handles storage of your files
  2. Your agent receives secure presigned URLs to access these files
  3. These URLs remain valid for 30 days after upload
  4. Files are accessible only to your organization’s agents

All uploaded files are stored securely on our platform. Your agent doesn’t need to handle file storage or download logic - it will automatically receive properly formatted URLs to access the files.

​
Synchronous vs Asynchronous Requests

​
Synchronous Mode

curl --location "https://webhook.xpander.ai?asynchronous=false" \
--header "x-api-key: YOUR_API_KEY" \
--header "Content-Type: application/json" \
--data '{"source_node_id": "YOUR_SOURCE_NODE_ID", "agent_id": "YOUR_AGENT_ID", "prompt": "What can you do?"}'
  • HTTP request remains open until agent completes
  • Returns complete execution details and results
  • Best for immediate responses and short tasks

Response:

{
  "result": {
    "id": "9642f5dd-e535-465f-bdaf-89be6ecaa2d5",
    "status": "completed",
    "result": "I specialize in extracting text from image and PDF files using Optical Character Recognition (OCR) technology. If you provide me with a file in a supported format (pdf, png, jpeg, gif, webp), I can extract the text content for you.",
    "source": "webhook"
  }
}

​
Asynchronous Mode

curl --location "https://webhook.xpander.ai?asynchronous=true" \
--header "x-api-key: YOUR_API_KEY" \
--header "Content-Type: application/json" \
--data '{"source_node_id": "YOUR_SOURCE_NODE_ID", "agent_id": "YOUR_AGENT_ID", "prompt": "What can you do?"}'
  • Returns immediately while agent processes in background
  • Best for long-running tasks and large file processing
  • Allows your application to continue execution

Response:

{
  "result": "Started"
}

​
Example: OCR Document Processing

This example shows how to extract text from a document using the OCR agent:

curl --location "https://webhook.xpander.ai?asynchronous=false" \
--header "x-api-key: YOUR_API_KEY" \
--form "prompt=Extract text from this document" \
--form "files=@/path/to/your/document.pdf" \
--form "source_node_id=YOUR_SOURCE_NODE_ID" \
--form "agent_id=YOUR_AGENT_ID"

The OCR agent handles multiple document formats (PDFs and images) and preserves formatting when possible, including tables and structured content.

​
Sample OCR Result

{
  "result": {
    "id": "07d6f375-53e9-4aa3-a7af-c36ce99a07d8",
    "status": "completed",
    "result": "## Financial Statement\n\n## ACCOUNT SUMMARY FOR PERIOD ENDED SEPTEMBER 30, 2024\n\n| Description | Amount | Percentage |\n|------------|--------|------------|\n| Opening Balance | 50,000 | - |\n| Deposits | 25,000 | - |\n| Withdrawals | (10,000) | - |\n| Fees | (1,500) | 3% |\n| Interest | 1,200 | 2.4% |\n| Closing Balance | 64,700 | - |",
    "source": "webhook"
  }
}

​
Monitoring Webhook Activity

xpander.ai provides a comprehensive monitoring interface for webhook calls:

Webhook Monitoring Interface

The monitoring dashboard displays:

  • Complete execution logs
  • File processing details
  • Performance metrics
  • Full request/response data

​
Common Use Cases

Workflow Automation

Integrate with platforms like Zapier, Make.com, or n8n to trigger document processing based on external events.

Document Processing

Extract structured data from documents to automate data entry and analysis workflows.