Webhooks allow you to trigger xpander.ai agents from any external system that can make HTTP requests. Perfect for integrating with existing workflows, automation platforms, or custom applications.
Webhook Configuration Interface

Webhook Configuration Interface

​
Setting Up Your Webhook

To enable webhooks for your agent:
1

Access Task Sources

In the Workbench, navigate to your agent and click the Task Sources tab.
2

Enable Webhooks

Toggle the Webhook task source and click Configure and test.
3

Get Your Webhook URL

Copy the provided webhook URL and API key from the configuration panel.
4

Test Your Webhook

Use the built-in test interface or the provided curl snippet to verify your setup.

​
Making Requests

All webhook requests use POST to the root endpoint with your authentication and agent configuration.

​
Basic Request Structure

curl --location 'https://webhook.xpander.ai/?agent_id=YOUR_AGENT_ID' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '{
    "prompt": "Analyze this data",
    "custom_field": "any value"
  }'

​
Parameters

​
Required Parameters

ParameterTypeLocationDescription
agent_idstringQuery or BodyYour agent’s unique identifier
x-api-keystringHeader or QueryYour API key for authentication

​
Optional Parameters

ParameterTypeDefaultDescription
promptstring""Text prompt to send to your agent
asynchronousbooleanfalseProcess in background and return immediately
task_idstring-Associate request with specific task ID
getterstring-Extract specific data from response (e.g., "result.summary")
You can include any additional fields in your request - they’ll all be passed to your agent for processing. This gives you complete flexibility for custom data structures.

​
Input Formats

Webhooks support multiple content types to fit your integration needs:
Perfect for structured data and API integrations.
curl --location 'https://webhook.xpander.ai/?agent_id=YOUR_AGENT_ID' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '{
    "prompt": "Process this order",
    "order_data": {
      "id": 12345,
      "items": ["item1", "item2"],
      "total": 99.99
    }
  }'

​
Execution Modes

Synchronous

Best for: Immediate responses, short tasks, interactive workflows
  • Waits for agent to complete processing
  • Returns full results in the response
  • Request remains open until finished

Asynchronous

Best for: Long-running tasks, file processing, background jobs
  • Returns immediately with task started confirmation
  • Agent processes in the background
  • Prevents timeouts for long operations

​
Synchronous Response

{
  "id": "task-123",
  "agent_id": "your-agent-id", 
  "status": "completed",
  "result": "Agent's response here",
  "created_at": "2024-01-01T12:00:00Z",
  "completed_at": "2024-01-01T12:00:05Z"
}

​
Asynchronous Response

{
  "status": "Started"
}

​
File Processing

Files must be uploaded directly using multipart/form-data. URLs to external files are not supported - the webhook service needs the actual file content.

​
Supported File Types

  • Documents: PDF, DOC, DOCX, TXT
  • Images: PNG, JPEG, GIF, WEBP, SVG
  • Spreadsheets: XLS, XLSX, CSV
  • Archives: ZIP (contents extracted automatically)

​
Multiple File Upload

curl --location 'https://webhook.xpander.ai/?agent_id=YOUR_AGENT_ID&asynchronous=true' \
  --header 'x-api-key: YOUR_API_KEY' \
  --form 'prompt="Process these documents"' \
  --form 'file1=@document1.pdf' \
  --form 'file2=@spreadsheet.xlsx' \
  --form 'file3=@image.png'
For large file batches (10+ files), use asynchronous mode and consider breaking uploads into smaller batches of 5-10 files for optimal performance.

​
Advanced Features

​
Data Extraction with Getter

Use the getter parameter to extract specific data from your agent’s response: 
# Extract just the summary from a complex response
curl --location 'https://webhook.xpander.ai/?agent_id=YOUR_AGENT_ID&getter=result.summary' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '{"prompt": "Analyze quarterly report"}'
Instead of full response: 
{
  "result": {
    "analysis": {...},
    "summary": "Q4 revenue increased 15%",
    "details": {...}
  }
}
Returns just: 
"Q4 revenue increased 15%"

​
Parameter Priority

When the same parameter appears in multiple places:
  1. Query parameters (highest priority)
  2. Request body parameters
  3. Default values
# The query parameter 'prompt' will override the body 'prompt'
curl --location 'https://webhook.xpander.ai/?agent_id=YOUR_AGENT_ID&prompt=From query' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '{"prompt": "From body", "data": "additional info"}'
# Agent receives: prompt="From query", data="additional info"

​
Integration Examples

Zapier Integration

Connect any Zapier trigger to your agent for automated workflows.

Form Processing

Process contact forms, surveys, and user submissions automatically.

Document Analysis

Extract data from uploaded documents, invoices, and contracts.

API Integration

Integrate agents into your existing applications and services.

​
JavaScript Example

const response = await fetch('https://webhook.xpander.ai/?agent_id=YOUR_AGENT_ID', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    prompt: 'Process customer inquiry',
    customer_data: {
      name: 'John Doe',
      email: 'john@example.com',
      message: 'I need help with my order'
    }
  })
});

const result = await response.json();
console.log('Agent response:', result.result);

​
Python Example

import requests

response = requests.post(
    'https://webhook.xpander.ai/',
    params={'agent_id': 'YOUR_AGENT_ID'},
    headers={'x-api-key': 'YOUR_API_KEY'},
    json={
        'prompt': 'Analyze sales data',
        'data': {
            'month': 'January',
            'sales': [1000, 1200, 1500]
        }
    }
)

result = response.json()
print(f"Analysis: {result['result']}")

​
Error Handling

​
Best Practices

Use Async for Large Tasks

Set asynchronous=true for file processing, complex analysis, or any task taking >30 seconds.

Implement Retry Logic

Add exponential backoff retry for transient failures (5xx errors).

Validate Responses

Always check the HTTP status code and handle error responses appropriately.

Use Getter for Large Responses

Extract only the data you need to reduce response size and improve performance.