Receive automated notifications when tasks complete
Overview
Webhooks enable your application to receive real-time notifications when tasks complete. Instead of polling for results, configure a webhook endpoint to receive data automatically when the AI agent finishes its work.Use cases:
Automated data pipelines that trigger on task completion
Real-time notifications to downstream systems
Integration with third-party services and APIs
Event-driven architectures without polling overhead
Configuration
Add a webhook object to your session or task request to enable webhook notifications.
Webhook Parameters
Parameter
Type
Required
Description
name
string
Yes
Identifier for this webhook (useful for logging)
url
string
Yes
HTTPS endpoint URL to receive the webhook
auth
string
No
Authorization header value sent with the request
submittedData
string
Yes
Specifies what data to include in the payload
submittedData Options
Value
Description
Best For
"ai_response"
The response from the AI (text, structured_json, or structured_csv): only the results/output from the LLM
Use submittedData: "ai_response" to receive only the AI’s output (text, structured_json, or structured_csv), reducing payload size and simplifying your webhook handler.
Webhook Payload
The payload sent to your endpoint depends on the submittedData setting.
Generate unique tokens for different webhook endpoints to limit exposure if one is compromised.
Error Handling
If your webhook endpoint fails to respond or returns an error, the webhook delivery will not be retried. Ensure your endpoint is reliable and returns quickly.
Webhook deliveries are not retried on failure. Design your endpoint to be highly available and respond within 30 seconds.
Recommended Approach
Acknowledge receipt immediately with a 200 status
Process the data asynchronously
Implement your own retry logic if needed
app.post('/webhooks/products', async (req, res) => { // Acknowledge immediately res.status(200).json({ received: true }); // Process asynchronously try { await processProductAsync(req.body); } catch (error) { console.error('Processing failed:', error); // Queue for retry in your own system await queueForRetry(req.body); }});
Use Cases
Data Pipeline Automation
Automatically ingest extracted data into your database or data warehouse.