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:

Decision	Option A	Option B
Context passing	Full context (accurate, expensive)	Selective context (cheap, focused)
Error handling	Agent retries	Orchestrator retry logic
Parallelism	Sequential delegation	Parallel delegation with merge

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

Architecture 4: Scheduled Pipeline

Agents run on schedules, each feeding data to the next.

                    Schedule: Daily 6 AM
                         │
                         ▼
                  ┌──────────────┐
                  │ Data Fetch   │ Pulls from APIs/databases
                  │ Lindy        │
                  └──────┬───────┘
                         │ Agent Send Message
                         ▼
                  ┌──────────────┐
                  │ Analysis     │ Processes & summarizes
                  │ Lindy        │
                  └──────┬───────┘
                         │ Agent Send Message
                         ▼
                  ┌──────────────┐
                  │ Report       │ Formats & delivers
                  │ Lindy        │
                  │  → Slack     │
                  │  → Email     │
                  └──────────────┘

Best for: Daily reports, weekly digests, scheduled data processing

Architecture 5: Chat + Knowledge Base

Agent exposed through a chat surface currently supported by the workspace and grounded in an approved knowledge base.

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  Website     │     │ Lindy Agent  │     │ Knowledge    │
│  (Embed      │◀──▶ │              │◀──▶ │ Base         │
│   Widget)    │     │ Chat Trigger │     │ PDFs, Docs,  │
└──────────────┘     │ + KB Search  │     │ Websites     │
                     │ + Condition  │     └──────────────┘
                     │ + Escalate   │
                     └──────────────┘
                            │
                            ▼ (if escalation needed)
                     ┌──────────────┐
                     │ Slack DM to  │
                     │ human agent  │
                     └──────────────┘

Deployment boundary:

• Publish only through a chat or embed surface shown in current Lindy documentation or the workspace UI; do not paste an unverified script URL from a template.
• Approve each knowledge source, record its owner and refresh cadence, and test that revoked or sensitive documents are not retrievable.
• Configure result count and matching behavior from measured answer quality rather than hard-coded template values.
• Add human escalation and an explicit no-answer path before public exposure.

Best for: Customer support, FAQ bots, internal knowledge assistants

Architecture Decision Matrix

Pattern	Choose when	Measure before approval	Primary risk
Simple webhook	One bounded async workflow	end-to-end latency, duplicate rate	callback spoofing
Event-driven pipeline	Multiple producers or replay required	queue lag, retry volume	event/data fan-out
Multi-agent workflow	Specialist boundaries improve quality	completion rate, context size	authority drift
Scheduled pipeline	Work is naturally periodic	freshness, missed-run recovery	silent schedule gaps
Chat + knowledge base	Users need interactive retrieval	answer quality, escalation rate	sensitive retrieval

Error Handling

Pattern	Failure Mode	Recovery
Simple webhook	Agent fails or callback is rejected	retain receipt; retry within budget; escalate
Event-driven	Router or downstream unavailable	keep dura

---

Content truncated.