Overview
Webhooks provide a push-based mechanism for receiving automation task results in real-time. Instead of continuously polling for task status, Narada Cloud automatically sends the response to your specified endpoint when the task completes.Real-time Updates
Receive results immediately when tasks complete, eliminating polling delays
Reduced Load
Lower server load and API usage compared to continuous polling
Scalable
Handle high-volume automation workflows efficiently
Efficient
Process automation results without continuous API polling
How Webhooks Work
When you submit an automation task via the Remote Dispatch API, you can provide acallbackUrl. Once the task completes, Narada Cloud sends an HTTP POST request to your endpoint with the complete task results.
1
Submit Task with Webhook
Include
callbackUrl when creating a remote dispatch request2
Task Executes
Narada Cloud processes your automation task asynchronously
3
Receive Callback
When complete, Narada Cloud POSTs the results to your callback URL
4
Process Results
Your endpoint receives and processes the webhook payload
Webhooks are recommended for production applications where real-time notifications and scalability are important.
Configuration
Setting Up a Webhook Endpoint
Configure webhooks by providing thecallbackUrl parameter when creating a remote dispatch request:
Configuration Parameters
The HTTPS URL where Narada Cloud will send the webhook POST request. Must be a publicly accessible endpoint that accepts POST requests.
Optional secret key included in the webhook payload for verification. Use this to validate that webhook requests are genuinely from Narada Cloud.
Webhook Payload
When an automation task completes, Narada Cloud sends a POST request to yourcallbackUrl with the following JSON payload:
Payload Structure
The unique identifier for the automation task. Use this to correlate webhook notifications with your original requests.
The
callbackSecret you provided when creating the task. Returns null if no secret was specified.Current status of the automation task. Possible values:
"input-required"- Task requires additional user input"success"- Task completed successfully"error"- Task failed with an error
The browser window ID where the task was executed. Returns
null if not applicable.The automation task response data containing the results.
ISO 8601 timestamp when the task was initially created.
ISO 8601 timestamp when the task completed.
Usage statistics for the automation task. Returns
null if not available.Example Payloads
- Success
- Error
- Input Required
- Structured Output
Implementing a Webhook Endpoint
Basic Implementation
Create an endpoint that receives and processes webhook notifications:- Node.js (Express)
- Python (FastAPI)
Response Requirements
Your webhook endpoint must:1
Accept POST Requests
Configure your endpoint to accept HTTP POST requests with JSON payloads.
2
Respond Quickly
Return a
200 OK response promptly to acknowledge receipt. Perform long-running operations asynchronously.Security Best Practices
1. Use HTTPS
Always use HTTPS endpoints to ensure yourcallbackSecret and webhook data are encrypted in transit.
2. Verify the Secret
Always validate thecallbackSecret to ensure webhooks are from Narada Cloud:
Common Issues
Webhook Not Received
Webhook Not Received
Possible causes:
- Callback URL is not publicly accessible
- Firewall blocking incoming requests
- HTTPS certificate issues
- Server is down or not responding
- Verify your endpoint is publicly accessible
- Check firewall and security group settings
- Ensure valid SSL certificate
- Monitor server uptime and health
Comparison: Webhooks vs Polling
| Feature | Webhooks | Polling |
|---|---|---|
| Response Time | Immediate | Delayed by poll interval |
| Server Load | Low | Higher (active requests) |
| Implementation | Moderate complexity | Simple |
| Firewall Friendly | Requires open ports | Yes |
| Scalability | Excellent | Limited |
| Real-time Updates | Yes | No |
| API Efficiency | High | Lower |
| Production Ready | Yes (recommended) | Yes |
Best Practices Summary
Respond Quickly
Return
200 OK promptly and process long-running tasks asynchronouslyValidate Secret
Always verify the callbackSecret to ensure webhooks are from Narada Cloud
Monitor & Log
Maintain comprehensive logs for debugging and monitoring webhook delivery
Secure Your Endpoint
Use HTTPS to protect your callbackSecret and webhook data in transit
Next Steps
Remote Dispatch API
Learn how to submit automation tasks with webhook configuration
Get Task Status
Understand the polling alternative for receiving task results
Error Handling
Implement robust error handling for your automation workflows
JSON Schema
Structure webhook responses with JSON Schema for reliable data extraction