Webhooks

Receive real-time notifications when automation tasks complete

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 a callbackUrl. 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 request

2. 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 the callbackUrl parameter when creating a remote dispatch request:

cURL

curl -X POST 'https://api.narada.ai/fast/v2/remote-dispatch' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "prompt": "/Operator search for software engineering jobs and count the results",
    "browserWindowId": "your-browser-window-id",
    "callbackUrl": "https://your-domain.com/api/narada/webhook",
    "callbackSecret": "your-secret-key-here"
  }'

Configuration Parameters

callbackUrl · string

The HTTPS URL where Narada Cloud will send the webhook POST request. Must be a publicly accessible endpoint that accepts POST requests.

callbackSecret · string

Optional secret key included in the webhook payload for verification. Use this to validate that webhook requests are genuinely from Narada Cloud.

HTTPS Required: Your callback URL must use HTTPS to ensure your callbackSecret and webhook data are encrypted in transit.

Webhook Payload

When an automation task completes, Narada Cloud sends a POST request to your callbackUrl with the following JSON payload:

Payload Structure

requestId · string · required

The unique identifier for the automation task. Use this to correlate webhook notifications with your original requests.

secret · string | null

The callbackSecret you provided when creating the task. Returns null if no secret was specified.

status · string · required

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

browserWindowId · string | null

The browser window ID where the task was executed. Returns null if not applicable.

response · object · required

The automation task response data containing the results.

Show Response Object Properties

text · string

The main response text from the automation task.

structuredOutput · object

Structured data if you specified a responseFormat in your original request. See JSON Schema documentation for details.

createdAt · string · required

ISO 8601 timestamp when the task was initially created.

completedAt · string · required

ISO 8601 timestamp when the task completed.

usage · object | null

Usage statistics for the automation task. Returns null if not available.

Show Usage Object Properties

actions · integer

Number of actions performed during the automation task.

credits · integer

Number of credits consumed by the task.

Example Payloads

Success

{
  "requestId": "req_abc123def456",
  "secret": "your-secret-key-here",
  "status": "success",
  "browserWindowId": "window_xyz789",
  "response": {
    "text": "Found 1,234 software engineering job listings in the search results."
  },
  "createdAt": "2024-11-21T10:00:00.000000+00:00",
  "completedAt": "2024-11-21T10:00:45.000000+00:00",
  "usage": {
    "actions": 12,
    "credits": 5
  }
}

Implementing a Webhook Endpoint

Basic Implementation

Create an endpoint that receives and processes webhook notifications:

Node.js (Express)

const express = require('express');
const app = express();

app.use(express.json());

app.post('/api/narada/webhook', (req, res) => {
  const payload = req.body;

  // Verify the secret if provided
  if (payload.secret !== process.env.NARADA_CALLBACK_SECRET) {
    return res.status(401).json({ error: 'Invalid secret' });
  }

  // Process the webhook payload
  console.log(`Task ${payload.requestId} completed with status: ${payload.status}`);

  if (payload.status === 'success') {
    console.log('Response:', payload.response.text);
    // Handle successful completion
    handleSuccess(payload);
  } else if (payload.status === 'error') {
    console.error('Task failed:', payload.response.text);
    // Handle error
    handleError(payload);
  } else if (payload.status === 'input-required') {
    console.log('Input required:', payload.response.text);
    // Handle input requirement
    handleInputRequired(payload);
  }

  // Always respond with 200 to acknowledge receipt
  res.status(200).json({ received: true });
});

function handleSuccess(payload) {
  // Your success handling logic
  // Store results, trigger next steps, etc.
}

function handleError(payload) {
  // Your error handling logic
  // Log errors, retry tasks, send alerts, etc.
}

function handleInputRequired(payload) {
  // Your input handling logic
  // Notify users, pause workflows, etc.
}

app.listen(3000, () => {
  console.log('Webhook endpoint listening on port 3000');
});

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 your callbackSecret and webhook data are encrypted in transit.

# ✅ Good
https://api.yourdomain.com/webhook

# ❌ Bad
http://api.yourdomain.com/webhook

2. Verify the Secret

Always validate the callbackSecret to ensure webhooks are from Narada Cloud:

if (payload.secret !== process.env.NARADA_CALLBACK_SECRET) {
  return res.status(401).json({ error: 'Unauthorized' });
}

Store your callbackSecret in environment variables, never in your code or version control.

Common Issues

Webhook Not Received

Possible causes:

• Callback URL is not publicly accessible
• Firewall blocking incoming requests
• HTTPS certificate issues
• Server is down or not responding

Solutions:

• 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

Use webhooks for production applications where real-time notifications are important. Use polling via Get Task Status when webhook setup is not feasible.

Best Practices Summary

Respond Quickly

Return 200 OK promptly and process long-running tasks asynchronously

Validate 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

Production Checklist: Before deploying, ensure you have HTTPS enabled, secret validation implemented, and comprehensive logging.