Skip to main content
POST
/
api
/
test-workflow
Test Workflow
curl --request POST \
  --url https://api.example.com/api/test-workflow
{
  "success": true,
  "data": {},
  "executionId": "<string>",
  "workflowId": "<string>",
  "message": "<string>",
  "details": {
    "triggerType": "<string>",
    "metadata": {}
  }
}

​
Overview

The n8n_test_workflow tool triggers workflow execution through externally-accessible trigger types. It automatically detects the trigger type from your workflow or accepts an explicit trigger type parameter.
Important: Only workflows with webhook, form, or chat triggers can be executed externally. Other trigger types (schedule, manual, etc.) are not supported by n8n’s public API.

​
Supported Trigger Types

​
Webhook Trigger

Triggers via HTTP webhook endpoint. Supports GET, POST, PUT, and DELETE methods. Use Cases:
  • REST API endpoints
  • Incoming webhooks from external services
  • Custom HTTP integrations

​
Form Trigger

Submits form data via multipart/form-data POST request. Use Cases:
  • Web form submissions
  • File uploads
  • Multi-field data collection
Supported Field Types:
  • Text, textarea, email, number, password
  • Date, dropdown, checkbox
  • File uploads (base64 encoded, max 10MB)
  • Hidden fields and HTML elements

​
Chat Trigger

Sends chat messages with session continuity support. Use Cases:
  • AI chatbots
  • Conversational interfaces
  • Multi-turn dialogues

​
Parameters

​
Required

​
workflowId
string
required
The ID of the workflow to execute. Must contain a webhook, form, or chat trigger node.

​
Trigger Selection

​
triggerType
enum
default:"auto-detect"
Explicit trigger type. Auto-detected from workflow if omitted.

​
Webhook Options

​
httpMethod
enum
default:"POST"
HTTP method for webhook triggers.
​
webhookPath
string
Override the webhook path. By default, uses the path configured in the workflow’s webhook node.
​
data
object
Payload data for the request:
  • Webhook: Request body (POST/PUT/DELETE) or query params (GET)
  • Form: Form field values (use field-0, field-1, etc. as keys)
  • Chat: Additional context data
Example - Webhook Data
{
  "data": {
    "userId": "123",
    "action": "process",
    "items": ["item1", "item2"]
  }
}
​
headers
object
Custom HTTP headers to include in the request.
Example - Custom Headers
{
  "headers": {
    "X-Custom-Header": "value",
    "Authorization": "Bearer token123"
  }
}

​
Chat Options

​
message
string
required
The message to send to the chat trigger. Required when triggerType is chat.
​
sessionId
string
Session identifier for conversation continuity. If omitted, a new session ID is auto-generated.
Example Session ID
session_1234567890_abc123def

​
Execution Options

​
timeout
number
default:"120000"
Request timeout in milliseconds. Default is 2 minutes (120000ms).
​
waitForResponse
boolean
default:"true"
Whether to wait for the workflow to complete execution:
  • true (default): Wait for complete execution and return results
  • false: Fire-and-forget mode, returns immediately

​
Response Fields

​
success
boolean
required
Indicates if the workflow was triggered successfully.
​
data
object
Execution result data returned by the workflow (when waitForResponse is true).
​
executionId
string
Unique identifier for the execution. Use with n8n_executions to retrieve execution details.
​
workflowId
string
The ID of the workflow that was executed.
​
message
string
Human-readable status message describing the execution result.
​
details
object
Additional execution metadata:

​
Examples

{
  "workflowId": "abc123",
  "data": {
    "name": "John Doe",
    "email": "[email protected]",
    "action": "subscribe"
  },
  "headers": {
    "X-Source": "mobile-app"
  }
}

​
Response Examples

{
  "success": true,
  "data": {
    "result": "processed",
    "recordsCreated": 3
  },
  "executionId": "exec_789xyz",
  "workflowId": "abc123",
  "message": "Workflow triggered successfully via webhook",
  "details": {
    "triggerType": "webhook",
    "metadata": {
      "duration": 1543,
      "webhookPath": "custom-endpoint",
      "httpMethod": "POST"
    }
  }
}

​
Security Features

​
SSRF Protection

All webhook URLs are validated before execution to prevent Server-Side Request Forgery attacks:
  • Blocks private IP ranges (10.x.x.x, 192.168.x.x, 127.x.x.x)
  • Blocks localhost and link-local addresses
  • Validates URL format and scheme

​
Workflow Activation

Webhook, form, and chat triggers require the workflow to be active in n8n. Inactive workflows cannot be triggered externally.

​
Best Practices

  • Let the system auto-detect trigger types when possible
  • Only specify triggerType explicitly when working with multi-trigger workflows
  • Check the workflow structure first if unsure about trigger configuration
  • Form fields use indexed naming: field-0, field-1, field-2, etc.
  • Field indices correspond to the order defined in the Form Trigger node
  • File uploads require base64 encoding with max 10MB size
  • Use the workflow’s form configuration to determine required fields
  • Always provide sessionId for multi-turn conversations
  • Session IDs should be unique per user/conversation
  • Include relevant context in the data parameter for better responses
  • Check success field before processing response data
  • Use executionId to retrieve detailed execution logs via n8n_executions
  • Handle timeout errors gracefully - long-running workflows may exceed default timeout
  • For async workflows, use waitForResponse: false and poll execution status
  • Use waitForResponse: false for long-running workflows to avoid timeouts
  • Poll execution status using n8n_executions with the returned executionId
  • Set appropriate timeout values based on expected workflow duration
  • For fire-and-forget scenarios, use shorter timeouts (5-10 seconds)

Build docs developers (and LLMs) love

Get started for freeTalk to us