n8n HTTP Long Polling Trigger

HTTP Long Polling trigger node for n8n with continuous polling support.

Version: 0.3.0

Features

• Continuous Polling: Uses trigger() method for continuous polling without relying on n8n's polling interval
• Long Polling Support: Supports long polling with configurable timeout
• Offset Tracking: Automatic offset/state management between requests with configurable increment (uses unique node ID to prevent conflicts when multiple nodes exist in same workflow)
• Flexible Configuration: Supports GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS methods
• Custom Headers & Query Parameters: Full control over HTTP request parameters (supports multiple values for same parameter name)
• JSONPath Support: Extract data arrays and offsets from complex JSON responses using simple JSONPath-like notation
• Debug Mode: Optional debug information (CURL command, offset values) in emitted data
• Error Handling: Robust error handling with automatic retry on failures
• Test Mode: Special handling for manual/test execution (polls until first data, then stops)

Installation

1. Copy this package to your n8n custom nodes directory:

   cp -r n8n-nodes-HTTP-long-pooling-trigger /path/to/n8n/custom/nodes/
   

2. Install dependencies:

   cd n8n-nodes-HTTP-long-pooling-trigger
   npm install
   npm run build
   

3. Restart n8n to load the new node

Usage

Basic Setup

1. Add "HTTP Long Polling Trigger" node to your workflow
2. Configure:
   • URL: Your API endpoint (e.g., https://platform-api.max.ru/updates)
   • Method: HTTP method (usually GET or POST)
   • Response Timeout: Timeout in seconds (for long polling, set to match server timeout, e.g., 60)

Max API Example

For Max API polling:

1. URL: https://platform-api.max.ru/updates
2. Method: GET
3. Send Headers: true
   • Authorization: Your Max API token
4. Send Query Parameters: true
   • limit: 100
   • timeout: 60 (for long polling)
5. Enable Offset Tracking: true
   • Offset Parameter Name: marker
   • Offset Location: Query Parameter
   • Offset Path in Response: marker
   • Real Data Path: updates
6. Response Timeout: 65 (slightly more than server timeout)

Telegram API Example

For Telegram getUpdates:

1. URL: https://api.telegram.org/bot<TOKEN>/getUpdates
2. Method: POST
3. Send Body: true
   • Body Content Type: JSON
   • JSON Body:

     {
       "limit": 100,
       "timeout": 60
     }
     

4. Enable Offset Tracking: true
   • Offset Parameter Name: offset
   • Offset Location: Body (JSON)
   • Offset Path in Response: result[-1].update_id
   • Real Data Path: result
5. Response Timeout: 65

How It Works

Unlike polling nodes that use poll() method (which are called by n8n on a schedule), this node uses trigger() method with an internal continuous loop:

1. When workflow is activated, trigger() starts an infinite loop
2. Each iteration makes an HTTP request to the configured endpoint
3. If long polling is enabled (via timeout parameter), the server keeps the connection open until new data arrives or timeout expires
4. When data is received, it's emitted to the workflow
5. Offset is automatically updated for the next request
6. Loop continues immediately with the next request (no delay between requests)
7. When workflow is deactivated, closeFunction() stops the loop

Differences from Polling Node

Parameters

HTTP Request

• Request Method: HTTP method (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS)
• URL: Endpoint URL (required)
• Headers: Custom HTTP headers (supports multiple headers)
• Query Parameters: URL query parameters (supports multiple values for same parameter name, e.g., ?param=value1&param=value2)
• Body: Request body (for POST/PUT/PATCH)
  • Body Content Type: JSON, Raw, Form-Data, Form Urlencoded
• Response Timeout: Client-side timeout in seconds (should be > server timeout for long polling, e.g., 65s for 60s server timeout)

Offset Tracking

• Enable Offset Tracking: Enable automatic offset/state management between requests
• Offset Parameter Name: Name of offset parameter (e.g., "offset", "marker", "since")
• Offset Location: Where to send offset (Query Parameter or Body (JSON))
• Offset Path in Response: JSONPath to extract offset from response (e.g., result[-1].update_id for Telegram, marker for Max API)
• Offset Increment: Value to add to numeric offset before saving (e.g., 1 for Telegram update_id + 1, 0 for Max marker as-is)
• Initial Offset: Initial offset value to use when starting. Priority: staticData > Initial Offset parameter > 0. In test mode, you can manually update this parameter in node settings if staticData is not persisted.

Data Filtering

• Real Data Path: JSONPath to check for data existence (e.g., result for Telegram, updates for Max API). If specified, node only emits when data exists at this path. Leave empty to always emit.

Debug

• Include Debug Info: If enabled, adds _debug field to emitted data with:
  • curlCommand: Full CURL command for the request
  • offsetUsed: Offset value used in the request
  • offsetAfterUpdate: Offset value after update

Notes

• For long polling to work, the server must support timeout parameter
• Response Timeout should be slightly higher than server timeout (e.g., server timeout 60s → client timeout 65s)
• The node continuously polls without delays between requests
• Offset tracking prevents duplicate processing of the same data
• In test/manual mode, the node polls until first data is received (respecting Real Data Path filter), then stops
• In production/trigger mode, the node continuously polls and emits data whenever it's available
• Multiple query parameters with the same name are supported (e.g., ?allowed_updates=message&allowed_updates=message_reaction)

Important: Offset Tracking in Test Mode

⚠️ Known Limitation: In test/manual execution mode, n8n does NOT persist staticData between test executions. This means:

• Each test execution might start with offset 0 (or the Initial Offset parameter value)
• Offset will be updated during the test execution and saved to staticData, but will reset on the next test execution
• This is a limitation of n8n's test mode, not a bug in this node

💡 Workaround for Test Mode:

• The node includes an "Initial Offset" parameter that you can manually update in node settings
• When staticData is empty (as in test mode), the node will use the "Initial Offset" parameter value
• After each test execution, you can manually update the "Initial Offset" parameter to the last offset value shown in the debug info
• The node automatically saves offset to staticData during execution, but in test mode this data is lost between executions

✅ In Production Mode (when workflow is active), staticData persists correctly:

• Offset is saved between workflow restarts
• Offset is maintained across all polling cycles
• No duplicate data will be processed

Workaround for Testing: If you need to test with offset persistence, activate the workflow (turn it ON) instead of using manual test execution. The workflow will then run in production mode where offset tracking works correctly.

Version History

0.3.0

• Improved error handling with better error messages
• Added try-catch blocks for robust operation
• Refactored JSONPath extraction into reusable function
• Fixed bug where currentRequest wasn't set in production mode
• Added comprehensive code comments and documentation
• Improved CURL command generation
• Better handling of edge cases (empty arrays, null values, etc.)

0.2.0

• Added Offset Increment parameter for configurable offset adjustment
• Added Include Debug Info option
• Improved offset tracking logic
• Enhanced CURL command logging

0.1.0

• Initial release
• Basic HTTP long polling functionality
• Offset tracking support
• Real Data Path filtering