Skip to content
Fyrn Docs

Quickstart

This guide creates a webhook-triggered flow that receives order data, transforms it, and delivers it to a target API endpoint.

What you’ll build

Section titled “What you’ll build”

A simple flow that:

  1. Receives incoming webhook payloads
  2. Transforms the data (formats fields, adds timestamps)
  3. Delivers to a target REST API
  4. Retries on failure with exponential backoff

  1. Install and authenticate

    Terminal window
    npm install -g @fyrn/cli
    fyrn login

  2. Initialize a project

    Terminal window
    mkdir my-first-flow && cd my-first-flow
    fyrn init

  3. Generate a flow with AI

    Terminal window
    fyrn flow create "Receive order webhooks and forward to my REST API with field mapping"

    fyrn generates a YAML flow config and prompts you to confirm. The generated flow looks like this:

    flows/order-webhook-to-api.yaml
    flow: order-webhook-to-api
    version: 1
    description: Receive order webhooks and forward to REST API
    

    source:
      connector: incoming-webhook
      trigger: webhook
    

    target:
      connector: my-api
      endpoint: /api/orders
      method: POST
    

    mapping:
      order_id: source.id
      customer_name: source.customer.name
      customer_email: source.customer.email
      total: source.total_price | decimal(2)
      currency: source.currency | uppercase
      received_at: '"" | now'
    

    on_error:
      retry: 3x exponential(30s)
      then: dead-letter

    Let’s break down each section:

    • source — where data comes from. trigger: webhook means this flow activates on inbound HTTP POST requests.
    • target — where data goes. The connector instance name, API endpoint path, and HTTP method.
    • mapping — field-by-field transformation using pipe syntax. source. references the inbound payload. The | operator chains transform functions.
    • on_error — retry 3 times with exponential backoff starting at 30s. After exhausting retries, send to the dead-letter queue.

  4. Test locally with sample data

    Create a test payload:

    test-payload.json
    {
      "id": "ORD-001",
      "customer": {
        "name": "Alice Johnson",
        "email": "alice@example.com"
      },
      "total_price": 149.5,
      "currency": "usd"
    }

    Run the transform locally:

    Terminal window
    fyrn flow test flows/order-webhook-to-api.yaml --sample-data test-payload.json

    Output shows the transformed payload:

    {
      "order_id": "ORD-001",
      "customer_name": "Alice Johnson",
      "customer_email": "alice@example.com",
      "total": "149.50",
      "currency": "USD",
      "received_at": "2026-02-26T10:30:00.000Z"
    }

  5. Deploy

    Terminal window
    fyrn flow deploy <flow-id>

    The CLI outputs the flow’s webhook URL:

    ✓ Deployed order-webhook-to-api v1
      Webhook URL: https://api.fyrn.dev/webhooks/receive/abc123

  6. Send a test webhook

    Terminal window
    curl -X POST https://api.fyrn.dev/webhooks/receive/abc123 \
      -H "Content-Type: application/json" \
      -d '{"id":"ORD-002","customer":{"name":"Bob Smith","email":"bob@example.com"},"total_price":299.99,"currency":"eur"}'

  7. Check the logs

    Terminal window
    fyrn logs tail <flow-id>

Your flow is live. Every webhook POST to that URL is transformed and delivered to your target API, with automatic retries on failure.

What’s next

Section titled “What’s next”