Lindy SDK Patterns

Lindy Integration Patterns

Overview

Use Lindy's documented integration primitives: Webhook Received for inbound calls, HTTP Request for outbound calls, Run Code for bounded transformations, and Send POST Request to Callback for the documented callback workflow. This is not an SDK guide: Lindy's current public documentation does not provide the package, client, agent CRUD, streaming, API key, or general API-host surface that older copies of this skill claimed.

Prerequisites

• Lindy workspace with an editable custom agent
• An application-owned HTTPS endpoint when outbound calls or callbacks are required
• A secret manager for the Lindy-generated Webhook Received secret and any separate credential owned by the target application
• Sanitized test fixtures and access to Tasks/Test Panel

Authentication and Trust Boundaries

• Inbound to Lindy: create the webhook in the Webhook Received trigger, select Generate Secret, store the one-time value, and send it as an Authorization bearer value. Use only the generated public.lindy.ai webhook URL.
• Outbound from Lindy: configure authentication required by the target service in the HTTP Request action. This is the target service's credential, not a Lindy API key.
• Callback: Lindy's webhook guide documents callbackUrl and Send POST Request to Callback, but does not document a Lindy callback signature. Treat callback content as untrusted unless the receiving application establishes its own authenticated boundary; never invent or claim a Lindy signing header.
• Keep inbound, outbound, and callback credentials distinct. Never put secrets in a prompt, body, query string, task title, log, or Run Code text output.

Instructions

1. Configure an Inbound Webhook Received Trigger

1. Add Webhook Received and create a named webhook.
2. Generate its secret and store it immediately; Lindy documents that it is shown once.
3. Choose follow-up behavior deliberately: same task, new task, or ignore.
4. Define a minimal request schema and reject oversized/unknown fields in the calling application before sending.
5. Send a sanitized fixture, then verify the new task in Tasks.

This is a small application wrapper around the documented webhook, not a Lindy SDK:

type Intake = { event: 'document.ready'; documentRef: string };

async function triggerLindyWebhook(input: {
  webhookUrl: string;
  webhookSecret: string;
  payload: Intake;
}): Promise<number> {
  const url = new URL(input.webhookUrl);
  if (
    url.protocol !== 'https:' ||
    url.hostname !== 'public.lindy.ai' ||
    !url.pathname.startsWith('/api/v1/webhooks/') ||
    url.username ||
    url.password
  ) {
    throw new Error('Refusing an unrecognized Lindy webhook URL');
  }
  if (!input.webhookSecret.trim()) throw new Error('Webhook secret is empty');
  if (!/^doc_[a-z0-9_-]{1,64}$/i.test(input.payload.documentRef)) {
    throw new Error('Invalid document reference');
  }

  const response = await fetch(url, {
    method: 'POST',
    redirect: 'error',
    headers: {
      Authorization: `Bearer ${input.webhookSecret}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(input.payload),
  });
  if (!response.ok) throw new Error(`Webhook rejected with status ${response.status}`);
  return response.status;
}

Do not blindly retry an ambiguous response: the public webhook documentation does not promise an idempotency key. Check Tasks and the application's operation record before a controlled retry.

2. Configure an Outbound HTTP Request

1. Add HTTP Request from Popular or By Lindy.
2. Use a fixed, allowlisted HTTPS URL rather than task-controlled host text.
3. Select the method and content type required by the target service.
4. Put the target service's protected credential in the appropriate header.
5. Constrain the body to named fields from previous steps; omit full source messages, headers, credentials, and unrelated context.
6. Branch on the documented status-code/response outputs and fail closed on rejected or malformed responses.

3. Use Run Code for Bounded Transformation

Lindy documents Python/JavaScript variables as strings and exposes result, text, and stderr to later steps. Parse, validate, bound, and return only the minimum data:

import json

data = json.loads(raw_items)
if not isinstance(data, list) or len(data) > 100:
    raise ValueError("raw_items must be a list with at most 100 entries")

allowed = []
for item in data:
    if not isinstance(item, dict) or set(item) != {"reference", "score"}:
        raise ValueError("unexpected item schema")
    reference = item["reference"]
    score = item["score"]
    if not isinstance(reference, str) or len(reference) > 64:
        raise ValueError("invalid reference")
    if not isinstance(score, (int, float)) or not 0 <= score <= 1:
        raise ValueError("invalid score")
    if score >= 0.5:
        allowed.append({"reference": reference, "score": score})

return {"count": len(allowed), "items": allowed}

Avoid printing input data: printed content becomes text. Prefer HTTP Request for network calls so URL, authentication, response status, and error branches remain visible in the workflow. Do not rely on an undocumented runtime, sandbox vendor, startup time, timeout value, or library version; check the current Run Code page.