n8n-nodes-webhook-wait

This is an n8n community node that provides a Webhook Wait functionality with custom correlation IDs (no executionId dependency).

What it does

The Webhook Wait node allows you to:

• ✅ Pause a workflow until an external webhook is called
• 🔑 Use custom correlation IDs instead of execution IDs
• 🔄 Match webhook calls to the correct waiting execution
• 💾 Support both in-memory and Redis storage for state management
• ⏱️ Configure timeouts and poll intervals
• 🌐 Works with any external system that can make HTTP requests

Key Features

🎯 Custom Correlation IDs

Unlike n8n's built-in Wait node (which requires executionId), this node lets you use your own identifiers like:

• Order IDs
• User IDs
• Request IDs
• Transaction IDs
• Any custom identifier

💾 Flexible Storage

• In-Memory: Fast, perfect for development (state lost on restart)
• Redis: Persistent, production-ready (survives restarts)

⚙️ Configurable Behavior

• Custom webhook paths
• HTTP method selection (GET, POST, PUT, PATCH)
• Configurable timeouts
• Adjustable poll intervals
• Custom response data

Installation

Via npm (Recommended)

npm install n8n-nodes-webhook-wait

Then restart your n8n instance.

Via n8n Community Nodes

1. Go to Settings > Community Nodes
2. Click Install
3. Enter: n8n-nodes-webhook-wait
4. Click Install

Manual Installation

1. Navigate to your n8n installation directory
2. Go to ~/.n8n/custom/
3. Clone this repository:

cd ~/.n8n/custom/
git clone https://github.com/yourusername/n8n-nodes-webhook-wait.git
cd n8n-nodes-webhook-wait
npm install
npm run build

4. Restart n8n

Usage

Basic Example

1. Add the Webhook Wait node to your workflow
2. Configure the node:
   • Set webhook path (e.g., order-callback)
   • Choose to auto-generate or provide a correlation ID
   • Set timeout (default: 300 seconds)
3. The node outputs:
   • correlationId: The ID used for matching
   • webhookUrl: The full webhook URL to call
   • webhookData: Data received from the webhook call
   • status: success or timeout

Example Workflow

Start
  ↓
[Create Order] → correlationId: "order-12345"
  ↓
[Webhook Wait] → Waits for webhook call
  ↓            (webhookUrl includes correlationId)
[Process Order] ← Continues when webhook is called

External System Integration

When your workflow reaches the Webhook Wait node, call the webhook URL from your external system:

# Example: Call the webhook with correlation ID
curl -X POST "https://your-n8n.com/webhook/order-callback?correlationId=order-12345" \
  -H "Content-Type: application/json" \
  -d '{"status": "paid", "amount": 100}'

Using Redis (Production)

For production environments, use Redis for persistent state:

1. Install Redis: docker run -d -p 6379:6379 redis
2. In the node configuration:
   • Set Storage Type to Redis
   • Set Redis Connection to redis://localhost:6379

Advanced: Using Existing Correlation ID

If you already have an identifier from previous nodes:

1. Set Generate Correlation ID to false
2. Set Correlation ID to: {{$json["orderId"]}}

Node Parameters

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | Webhook Path | string | webhook-wait | The path for the webhook URL | | HTTP Method | dropdown | POST | HTTP method to listen for | | Correlation ID Field | string | correlationId | Field name containing the correlation ID | | Generate Correlation ID | boolean | true | Auto-generate a unique ID | | Correlation ID | string | - | Custom ID (when not auto-generating) | | Timeout (seconds) | number | 300 | Max wait time | | Poll Interval (seconds) | number | 2 | How often to check for webhook call | | Response Mode | dropdown | immediately | How to respond to webhook | | Response Data | string | {"status": "received"} | Custom response JSON | | Storage Type | dropdown | memory | Where to store state | | Redis Connection | string | redis://localhost:6379 | Redis connection string |

Output Data

On Success

{
  "correlationId": "order-12345",
  "webhookUrl": "https://your-n8n.com/webhook/order-callback?correlationId=order-12345",
  "status": "success",
  "webhookData": {
    "body": { "status": "paid", "amount": 100 },
    "query": { "correlationId": "order-12345" },
    "headers": { "content-type": "application/json" },
    "method": "POST",
    "timestamp": 1706486400000
  }
}

On Timeout

{
  "correlationId": "order-12345",
  "webhookUrl": "https://your-n8n.com/webhook/order-callback?correlationId=order-12345",
  "status": "timeout",
  "error": "Webhook call timed out"
}

Use Cases

✅ Order Processing

Wait for payment confirmation from a payment gateway

✅ Approval Workflows

Wait for user approval via email link or web form

✅ External Integrations

Wait for callbacks from third-party services

✅ Async Operations

Wait for long-running background jobs to complete

✅ Human-in-the-Loop

Wait for manual actions or verifications

How It Works

1. Node Execution: When the workflow reaches this node, it:

   • Generates/uses a correlation ID
   • Registers a webhook endpoint
   • Stores pending state (memory or Redis)
   • Returns the webhook URL

2. Waiting Phase: The node polls the storage to check if:

   • The webhook was called with matching correlation ID
   • The timeout was reached

3. Webhook Call: When your external system calls the webhook:

   • Node extracts the correlation ID from the request
   • Stores the webhook data (body, headers, query params)
   • Marks the state as completed

4. Resume: The waiting node detects the completed state and continues with the webhook data

Comparison with Built-in Wait Node

| Feature | Webhook Wait (This Node) | Built-in Wait Node | |---------|-------------------------|-------------------| | Custom Correlation IDs | ✅ Yes | ❌ No (uses executionId) | | Persistent Storage | ✅ Redis support | ❌ Memory only | | Custom Identifiers | ✅ Any ID you want | ❌ Must use resumeUrl | | External System Friendly | ✅ Yes | ⚠️ Requires execution context | | Production Ready | ✅ Yes (with Redis) | ⚠️ Limited |

Troubleshooting

Webhook not receiving calls

• Check that your n8n instance is accessible from the external system
• Verify the webhook URL is correct
• Check firewall/network settings
• Ensure the correlation ID matches exactly

Timeout issues

• Increase the timeout value
• Check that the external system is actually calling the webhook
• Verify Redis connection (if using Redis)

Redis connection errors

• Ensure Redis is running: docker ps or redis-cli ping
• Check the connection string format: redis://host:port
• Verify network connectivity to Redis

Requirements

• n8n version: 0.220.0 or higher
• Node.js: v16 or higher
• Redis (optional, for persistent storage): 4.x or higher

Development

Build

npm install
npm run build

Lint

npm run lint
npm run lintfix

Format

npm run format

License

MIT

Author

Your Name
Email: [email protected]
GitHub: @yourusername

Support

• 🐛 Report Issues
• 💡 Feature Requests
• 📖 Documentation

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Changelog

1.0.0 (2026-01-28)

• Initial release
• Support for custom correlation IDs
• In-memory and Redis storage options
• Configurable timeouts and poll intervals
• Custom webhook responses

Related

• n8n - Workflow automation tool
• n8n Community Nodes - Official documentation
• n8n Node Development - Create your own nodes

Made with ❤️ for the n8n community