Integrating WebRun with n8n

n8n is a powerful workflow automation platform that connects to virtually any service via HTTP requests. WebRun's REST API makes it a natural fit—you can add AI-powered browser automation to your n8n workflows in minutes.

Why n8n + WebRun Work Well Together

n8n Cloud has a 100-second timeout for HTTP requests, comfortably above WebRun's 50-second inline response window. This means most browser automation tasks will complete and return results directly without requiring polling logic.

Feature	n8n Capability	WebRun Fit
HTTP Timeout	100 seconds	Most tasks complete in 10-40s
Retry Logic	Native support	Built-in error handling
Polling	Loop + Wait nodes	Simple implementation
Authentication	Header-based	Bearer token
Response Handling	JSON parsing	Direct JSON responses

Setting Up Your Credentials

Before building workflows, store your WebRun API key as a credential in n8n.

• Go to Settings → Credentials in n8n
• Click Add Credential → Header Auth
• Configure:

- Name: WebRun API - Name: Authorization - Value: Bearer YOUR_API_KEY

Now you can reference this credential in all your HTTP Request nodes.

Pattern 1: Single Task Execution

The simplest pattern—run one browser task and get results inline.

n8n HTTP Request Node Configuration

Method: POST URL: https://connect.webrun.ai/start/run-task Authentication: Predefined Credential → Header Auth → WebRun API Body Content Type: JSON Body:

{
  "taskDetails": "Go to news.ycombinator.com and return the top 5 posts with their titles, URLs, and point counts"
}

Example Response

{
  "success": true,
  "status": "complete",
  "result": {
    "type": "task_completed",
    "data": {
      "message": "Here are the top 5 Hacker News posts:\n1. \"Show HN: I built...\" - 342 points\n2. ..."
    }
  }
}

Extracting the Result

In the next node, access the result with:

{{ $json.result.data.message }}

Pattern 2: Multi-Step Sessions

For workflows requiring multiple sequential tasks in the same browser—like logging in, then performing actions.

Step 1: Create Session

HTTP Request Node: "Create Session"

Method: POST URL: https://connect.webrun.ai/start/start-session Body:

{
  "taskDetails": "Go to amazon.com",
  "startingUrl": "https://amazon.com"
}

Step 2: Send Follow-up Task

HTTP Request Node: "Search Products"

Method: POST URL: https://connect.webrun.ai/start/send-message Body:

{
  "sessionId": "{{ $('Create Session').item.json.sessionId }}",
  "message": {
    "actionType": "newTask",
    "newState": "start",
    "taskDetails": "Search for wireless mechanical keyboards and return the top 3 results with prices"
  }
}

Step 3: Terminate Session

HTTP Request Node: "End Session"

Method: POST URL: https://connect.webrun.ai/start/send-message Body:

{
  "sessionId": "{{ $('Create Session').item.json.sessionId }}",
  "message": {
    "actionType": "state",
    "newState": "terminate"
  }
}

Pro tip: Set terminateOnCompletion: true on your final task to auto-close the session and avoid idle charges.

Pattern 3: Polling for Long-Running Tasks

Some complex tasks take longer than 50 seconds. WebRun returns a pollUrl for these cases. Here's how to implement polling in n8n.

Workflow Structure

[Trigger] → [Run Task] → [IF: Complete?] → [Yes: Continue] → [Process Result]
                              ↓ No
                         [Wait 3s] → [Poll Status] → (loop back to IF)

Node 1: Run Task

HTTP Request Node: "Run Task"

{
  "taskDetails": "Research the top 10 AI startups founded in 2024, including funding amounts and key products"
}

Node 2: Check If Complete

IF Node: "Is Complete?"

Condition: {{ $json.status }} equals complete

Node 3: Wait (No branch)

Wait Node: 3 seconds

Node 4: Poll Status

HTTP Request Node: "Poll Status"

Method: GET URL: https://connect.webrun.ai/task/{{ $('Run Task').item.json.sessionId }}/{{ $('Run Task').item.json.taskId }}

Then loop back to the IF node to check again.

Important Polling Notes

• The polling endpoint (GET /task/:sessionId/:taskId) has no rate limit
• Poll every 2-3 seconds for optimal balance
• Add a maximum retry count (e.g., 60 attempts = 3 minutes) to prevent infinite loops

Pattern 4: Scheduled Browser Automation

Combine n8n's scheduling with WebRun for recurring automation tasks.

Example: Daily Competitor Price Monitoring

[Schedule Trigger: Daily 9am] 
    → [Run Task: Get competitor prices] 
    → [IF: Prices changed?] 
    → [Yes: Send Slack notification]
    → [Save to Google Sheets]

Schedule Trigger: Cron expression 0 9 *

Run Task Body:

{
  "taskDetails": "Go to competitor.com/pricing and extract all plan names and prices. Return as JSON array with format: [{plan: string, price: number}]"
}

Slack Node: Send price changes to a channel

Pattern 5: Dynamic Task Generation

Use n8n's data from other nodes to create dynamic WebRun tasks.

Example: Process URLs from a Spreadsheet

[Google Sheets: Get URLs] 
    → [Loop Over Items] 
    → [Run Task: Scrape each URL] 
    → [Aggregate results]

HTTP Request inside Loop:

{
  "taskDetails": "Go to {{ $json.url }} and extract the main article title, author, and publication date"
}

Handling Guardrails

WebRun's guardrail system pauses tasks when human input is needed (login credentials, CAPTCHA help, purchase confirmation). Here's how to handle them in n8n.

Detecting Guardrails

When polling, check for guardrail_trigger type:

IF Node Condition: {{ $json.type }} equals guardrail_trigger

Responding to Guardrails

HTTP Request Node: "Respond to Guardrail"

{
  "sessionId": "{{ $('Run Task').item.json.sessionId }}",
  "message": {
    "actionType": "guardrail",
    "taskDetails": "The login credentials are: [email protected] / password123",
    "newState": "resume"
  }
}

Automated Guardrail Handling

For predictable guardrails (like known login pages), you can automate responses:

[Poll] → [IF: Guardrail?] → [Yes: Check guardrail type] 
                                → [Login needed: Send credentials]
                                → [CAPTCHA: Send to human queue]
                            → [Resume task]

Complete Workflow Example: Lead Enrichment

Here's a production-ready workflow that enriches lead data using WebRun.

Use Case

Given a list of company names, find their websites, descriptions, and employee counts.

Workflow

[Webhook: Receive leads] 
    → [Loop Over Items]
    → [Run Task: Research company]
    → [Wait 2s between requests]
    → [Parse results]
    → [Save to Airtable]
    → [Respond to webhook]

Run Task Configuration

{
  "taskDetails": "Search for {{ $json.companyName }} company. Find their official website and extract: 1) Company description (1-2 sentences), 2) Approximate employee count, 3) Industry category. Return as JSON."
}

Parsing Results

Code Node: Parse Company Data

const result = $input.first().json.result.data.message;

// If WebRun returned JSON-formatted data
try {
  const parsed = JSON.parse(result);
  return [{
    json: {
      company: $('Loop Over Items').item.json.companyName,
      website: parsed.website,
      description: parsed.description,
      employees: parsed.employeeCount,
      industry: parsed.industry
    }
  }];
} catch (e) {
  // Handle unstructured response
  return [{
    json: {
      company: $('Loop Over Items').item.json.companyName,
      rawData: result
    }
  }];
}

Error Handling

Common Error Responses

Status Code	Meaning	n8n Handling
400	Missing taskDetails	Check input data
401	Invalid API key	Verify credentials
402	Insufficient balance	Alert + stop workflow
429	Rate limited	Wait + retry
503	No available instances	Wait + retry

Retry Configuration

In your HTTP Request node settings, enable:

• Retry On Fail: Yes
• Max Tries: 3
• Wait Between Tries: 5000ms
• Retry On Status Codes: 429, 503

Cost Optimization Tips

• Use /start/run-task for single tasks — Sessions auto-terminate, no cleanup needed

• Set terminateOnCompletion: true on the last task in multi-task workflows

• Be specific in task descriptions — Clearer instructions = faster completion = lower costs

• Batch related operations — One multi-step session costs less than multiple single sessions

• Set appropriate maxDuration — Prevent runaway tasks:

{
  "taskDetails": "Quick lookup task",
  "maxDuration": 30000
}

Rate Limits

WebRun enforces these limits per user:

Endpoint	Limit
/start/run-task	10/minute
/start/start-session	10/minute
/start/send-message	10/minute
GET /task/:sessionId/:taskId	Unlimited

For high-volume workflows, implement queuing or use n8n's built-in rate limiting features.

Quick Reference

Operation	Endpoint	Method
Single task	/start/run-task	POST
Create session	/start/start-session	POST
Send task/command	/start/send-message	POST
Check status	/task/:sessionId/:taskId	GET
Terminate	/start/send-message with newState: terminate	POST

Next Steps

• Get your API key at app.webrun.ai
• Start simple — Create a single-task workflow to test the integration
• Add complexity — Implement polling for longer tasks
• Monitor costs — Check your usage dashboard regularly

For more examples and detailed API documentation, visit docs.webrun.ai.