Lindy Reference Architecture

Lindy Reference Architecture

Overview

Choose an integration shape for Lindy workflows without inventing a public SDK or control-plane API. The supported application boundary in these patterns is a dashboard-created Lindy webhook trigger, optionally paired with Lindy's HTTP Request or callback action for outbound delivery.

Prerequisites

• Understanding of Lindy agent model (triggers, actions, skills)
• Familiarity with webhook-based architectures
• Production requirements defined (throughput, latency, reliability)
• Current workspace evidence for the triggers, actions, integrations, and plan entitlements you intend to use
• A separate secret for each Lindy trigger and a different secret for each callback receiver; neither belongs in source control or architecture diagrams

Instructions

1. Write the workload's trust boundaries before selecting a pattern: event producers, Lindy trigger, callback receiver, stores, operators, and third parties.
2. Record data classification, maximum payload size, expected event rate, recovery objective, and whether duplicate delivery is safe.
3. Select the smallest pattern below that meets those requirements. Treat product features as available only after verifying them in the current Lindy workspace.
4. For every webhook edge, require HTTPS, an exact approved hostname, a per-edge secret, schema validation, payload bounds, idempotency, bounded retry, and a dead-letter or manual recovery path.
5. Test authorized and unauthorized requests with synthetic data. A 2xx response is insufficient evidence unless the expected task or durable queue record exists.
6. Produce the architecture decision record and dataflow inventory described in Output, then have a security reviewer approve the exact deployment revision.

Trust-Boundary Contract

• A Lindy trigger URL is created in the dashboard and uses the documented https://public.lindy.ai/api/v1/webhooks/... shape. Validate https: and the exact public.lindy.ai hostname before attaching its Lindy-generated trigger secret.
• Authenticate your own event ingress independently. Do not reuse a Lindy trigger secret to protect your application or callback endpoint.
• Minimize and redact event data before enqueueing it. Do not forward credentials, session tokens, raw customer records, or unrestricted third-party webhook bodies.
• Acknowledge external events only after a durable, idempotent queue write. Check the Lindy response before marking delivery successful, and retry only transient failures with a strict attempt and elapsed-time budget.
• Installed skills and local configuration are consumers of this design; they are not publication sources and must never upload secrets or runtime state.

Architecture 1: Simple Webhook Integration

Single agent triggered by your application, results sent via callback.

┌─────────────┐       POST (webhook)       ┌──────────────┐
│  Your App   │ ─────────────────────────→  │ Lindy Agent  │
│             │                             │              │
│  /callback  │ ←─────────────────────────  │ HTTP Request │
│             │       POST (callback)       │   Action     │
└─────────────┘                             └──────────────┘

Implementation:

• Your app sends a bounded request to its dashboard-created Lindy webhook using that trigger's Lindy-generated bearer secret.
• When a response is required, pass an allowlisted callback URL or opaque callback ID.
• The Lindy workflow uses the currently available callback or HTTP Request action. Your callback receiver verifies its own distinct secret and accepts only the documented response schema.

Best for: Simple automations (email triage, lead scoring, content generation)

Architecture 2: Event-Driven Pipeline

Multiple event sources feed agents through a central webhook router.

┌──────────┐
│ Stripe   │──webhook──┐
└──────────┘           │
                       ▼
┌──────────┐     ┌───────────┐     ┌──────────────┐
│ Shopify  │──→  │  Router   │──→  │ Lindy Agents │
└──────────┘     │  Service  │     │              │
                 └───────────┘     │ • Order Bot  │
┌──────────┐           ▲          │ • Support Bot│
│ Your App │──webhook──┘          │ • Analytics  │
└──────────┘                      └──────────────┘

Implementation:

authenticated producer
  -> schema and size validation
  -> field allowlist and redaction
  -> idempotent durable queue
  -> route chosen from a static event-to-trigger map
  -> exact HTTPS/public.lindy.ai sink check
  -> attach only that route's trigger secret
  -> bounded delivery and response validation
  -> receipt with event ID, route, attempt count, and status (never payload/secret)

Keep the event-to-trigger map in trusted configuration rather than request data. The downloadable implementation guide contains a secure sender boundary; it deliberately uses documented webhook primitives rather than an assumed SDK client.

Best for: Multiple event sources, different agents per event type

Architecture 3: Multi-Agent Society (Delegation)

Specialized workflows collaborate through the agent-to-agent actions or webhook edges that are visibly available in the current workspace. Do not assume an action name, delivery guarantee, or universal delegation entitlement from this document.

┌─────────────────┐
│ Orchestrator    │
│ Lindy           │
│ (receives       │
│  initial task)  │
└───┬────────┬────┘
    │        │
    ▼        ▼
┌────────┐ ┌────────┐
│Research│ │Analysis│
│ Lindy  │ │ Lindy  │
└───┬────┘ └───┬────┘
    │          │
    ▼          ▼
┌─────────────────┐
│ Writer Lindy    │
│ (synthesizes    │
│  final output)  │
└─────────────────┘

Setup in Lindy:

1. Define one bounded contract per specialist: accepted fields, result schema, timeout, and failure owner.
2. Select a currently supported agent-to-agent action or the secured webhook pattern.
3. Pass only the fields the specialist needs and correlate every result with a task ID.
4. Require the orchestrator to handle timeout, partial completion, duplicate results, and human escalation before synthesis.

Key decisions:

Best for: Complex tasks requiring multiple specialties (research + analysis + writing)