Build an API Gateway with Dynamic Sub-Workflow Routing

A single n8n webhook can act as an API gateway: one endpoint receives every request, then a Switch node routes each one to a dedicated sub-workflow based on the payload's event type. This gives you one URL to manage externally and centralizes authentication, validation, and logging, while each event type keeps its own sub-workflow for independent versioning and error handling.

What is the API gateway pattern in n8n?

A single webhook endpoint can act as an API gateway, routing incoming requests to different sub-workflows based on the payload content, a header value, or a URL path parameter. This simplifies external configuration (one URL to manage) and centralizes authentication, logging, and rate limiting.

Real-world example: Your internal tools send events to a single n8n endpoint. The gateway routes each event type to the appropriate processing workflow.

How do you route requests to sub-workflows?

Webhook Trigger
  Path: /webhook/gateway
  Method: POST
  Authentication: Header Auth (X-API-Key)
  |
  Code Node: Validate & Extract Route
  |
  Switch Node: Route by event_type
  |
  +-> "user.created"      -> Execute Sub-Workflow: Onboarding
  +-> "order.placed"      -> Execute Sub-Workflow: Order Processing
  +-> "alert.triggered"   -> Execute Sub-Workflow: Incident Response
  +-> Default             -> Respond with 400 (unknown event type)

Code Node: Validate and Extract Route

const body = $json.body;

// Validate required fields
if (!body.event_type) {
  throw new Error('Missing required field: event_type');
}

if (!body.payload) {
  throw new Error('Missing required field: payload');
}

// Add metadata for downstream processing
return [{
  json: {
    event_type: body.event_type,
    payload: body.payload,
    received_at: new Date().toISOString(),
    source_ip: $json.headers['x-forwarded-for'] || 'unknown',
    request_id: $json.headers['x-request-id'] ||
      `req_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`
  }
}];

Execute Sub-Workflow Node Configuration

{
  "workflowId": "={{ { 'user.created': 'wf_onboarding_001', 'order.placed': 'wf_orders_001', 'alert.triggered': 'wf_incidents_001' }[$json.event_type] }}",
  "workflowInputs": {
    "payload": "={{ $json.payload }}",
    "request_id": "={{ $json.request_id }}"
  }
}

Client Usage

# All events go to the same endpoint

curl -X POST https://n8n.example.com/webhook/gateway \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "event_type": "user.created",
    "payload": {
      "user_id": "usr_123",
      "email": "newuser@example.com",
      "plan": "pro"
    }
  }'

When should you use this pattern?

Tip: Sub-Workflow Benefits Using Execute Sub-Workflow nodes (instead of building all logic in one workflow) keeps each processing path in its own workflow with independent versioning, error handling, and execution history. The gateway workflow stays small and fast.

This pattern scales cleanly: adding a new event type means creating a new sub-workflow and adding one route to the Switch node.

Related: Use Path Parameters in Webhook URLs for Dynamic Routing · Use Edit Fields in "Map Each" Mode for Simple Renames