Fan-out Routing

Fan-out flows route each message to one or more targets based on a routing key and conditions. Use them when different payloads need different destinations.

Configuration

A fan-out flow uses the fan_out block instead of target or steps:

flow: payroll-distribution
version: 1
type: fan-out
source:
  connector: payroll-inbound
  trigger: webhook
fan_out:
  routing_key: source.client_id
  targets:
    - name: sap-hr
      instance: sap-production
      endpoint: /api/hr/payroll
      method: POST
      when: routing_key == "acme-corp"
      mapping:
        employee_id: source.employee.id
        gross_pay: source.amounts.gross | decimal(2)
    - name: default-hr
      instance: bamboohr-production
      endpoint: /api/payroll
      method: POST
      mapping:
        employeeId: source.employee.id
on_error:
  retry: 3x exponential(30s)
  then: dead-letter

Fan-out target fields

Field	Type	Required	Default	Description
name	string	Yes	—	Target name
instance	string	Yes	—	Connector instance name
endpoint	string	Yes	—	API endpoint path
method	string	No	POST	HTTP method
mapping	MappingBlock	No	—	Per-target field mapping
when	condition	No	—	Routing condition

---

Routing based on payload fields

The routing_key expression is evaluated against the incoming payload. Use when conditions on each target to match:

fan_out:
  routing_key: source.shipping_address.country
  targets:
    - name: eu-warehouse
      instance: warehouse-eu
      endpoint: /api/orders
      method: POST
      when: routing_key == "FI" or routing_key == "DE" or routing_key == "FR"

    - name: us-warehouse
      instance: warehouse-us
      endpoint: /api/orders
      method: POST
      when: routing_key == "US" or routing_key == "CA"

    - name: intl-warehouse
      instance: warehouse-international
      endpoint: /api/orders
      method: POST

---

Default branches

Targets without a when condition act as the default — they receive all messages that don’t match any conditional target.

---

Per-target mapping

Each target can have its own mapping to transform data for that specific destination:

targets:
  - name: sap-hr
    instance: sap-production
    endpoint: /api/hr/payroll
    method: POST
    when: routing_key == "acme-corp"
    mapping:
      employee_id: source.employee.id
      gross_pay: source.amounts.gross | decimal(2)
      currency: source.currency | uppercase

---

Example: Route orders by region

flow: regional-order-routing
version: 1
type: fan-out
source:
  connector: order-gateway
  trigger: webhook
fan_out:
  routing_key: source.region
  targets:
    - name: eu-fulfillment
      instance: warehouse-eu
      endpoint: /api/fulfill
      method: POST
      when: routing_key == "EU"
      mapping:
        order_ref: source.id
        items: source.line_items
        ship_to: source.shipping_address

    - name: us-fulfillment
      instance: warehouse-us
      endpoint: /api/fulfill
      method: POST
      when: routing_key == "US"
      mapping:
        orderNumber: source.id
        lineItems: source.line_items
        destination: source.shipping_address

    - name: apac-fulfillment
      instance: warehouse-apac
      endpoint: /api/orders/fulfill
      method: POST
      mapping:
        id: source.id
        items: source.line_items
on_error:
  retry: 3x exponential(30s)
  then: dead-letter

---

Fan-out vs switch step

Feature	Fan-out flow	Switch step
Flow type	Dedicated type: fan-out	Within multi-step flow
Routing	Per-target when conditions	Per-case when conditions
Mapping	Per-target mapping	Per-case mapping
Other steps	No — fan-out only	Yes — mix with call, tag, notify, etc.
Use when	Simple conditional routing	Complex pipelines with routing as one step

---

What’s next

• Flow Chaining — Trigger child flows with emit
• Saga Pattern — Distributed transactions with compensation
• DSL Reference — Full fan_out specification