lindy-local-dev-loop

Lindy Local Dev Loop

Overview

Lindy agents run on Lindy's managed infrastructure — you do not run agents locally. Local development focuses on building and testing the webhook receivers, callback handlers, and application code that Lindy agents interact with. Use ngrok or similar tunnels to expose local endpoints for Lindy webhook triggers.

Prerequisites

• Node.js 18+ or Python 3.10+
• ngrok or Cloudflare Tunnel for HTTPS tunneling
• Lindy account with at least one agent configured
• Completed lindy-install-auth setup

Instructions

Step 1: Create Webhook Receiver

// server.ts — Express webhook receiver for Lindy callbacks
import express from 'express';
import dotenv from 'dotenv';
dotenv.config();

const app = express();
app.use(express.json());

const WEBHOOK_SECRET = process.env.LINDY_WEBHOOK_SECRET;

// Verify Lindy webhook authenticity
function verifyWebhook(req: express.Request): boolean {
  const auth = req.headers.authorization;
  return auth === `Bearer ${WEBHOOK_SECRET}`;
}

// Receive Lindy agent callbacks
app.post('/lindy/callback', (req, res) => {
  if (!verifyWebhook(req)) {
    console.error('Unauthorized webhook attempt');
    return res.status(401).json({ error: 'Unauthorized' });
  }

  console.log('Lindy callback received:', JSON.stringify(req.body, null, 2));

  // Process the agent's output
  const { taskId, result, status } = req.body;
  console.log(`Task ${taskId}: ${status}`);

  res.json({ received: true });
});

// Health check for Lindy to verify endpoint
app.get('/health', (req, res) => res.json({ status: 'ok' }));

app.listen(3000, () => console.log('Webhook receiver running on :3000'));

Step 2: Expose Local Server via Tunnel

# Install and start ngrok
npm install -g ngrok
ngrok http 3000

# Output: https://abc123.ngrok.io -> http://localhost:3000
# Use this URL in Lindy webhook configuration

Step 3: Configure Lindy Agent to Call Your Endpoint

In the Lindy dashboard, add an HTTP Request action to your agent:

• Method: POST
• URL: https://abc123.ngrok.io/lindy/callback
• Headers: Content-Type: application/json
• Body (AI Prompt mode):

  Send the task result as JSON with fields: taskId, result, status
  

Or configure a webhook trigger pointing to your tunnel URL:

https://abc123.ngrok.io/lindy/webhook

Step 4: Create Test Harness

// test-trigger.ts — Fire a test webhook to your Lindy agent
import fetch from 'node-fetch';

async function triggerAgent() {
  const WEBHOOK_URL = process.env.LINDY_WEBHOOK_URL!;
  const SECRET = process.env.LINDY_WEBHOOK_SECRET!;

  const response = await fetch(WEBHOOK_URL, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${SECRET}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      action: 'test',
      data: { message: 'Hello from local dev', timestamp: new Date().toISOString() },
    }),
  });

  console.log(`Status: ${response.status}`);
  console.log(`Response: ${await response.text()}`);
}

triggerAgent();

Step 5: Watch Mode Development

// package.json scripts
{
  "scripts": {
    "dev": "tsx watch server.ts",
    "test:trigger": "tsx test-trigger.ts",
    "tunnel": "ngrok http 3000"
  }
}

# Terminal 1: Start server with auto-reload
npm run dev

# Terminal 2: Start tunnel
npm run tunnel

# Terminal 3: Fire test triggers
npm run test:trigger

Step 6: Environment Configuration

# .env
LINDY_API_KEY=lnd_live_xxxxxxxxxxxx
LINDY_WEBHOOK_SECRET=whsec_xxxxxxxxxxxx
LINDY_WEBHOOK_URL=https://public.lindy.ai/api/v1/webhooks/YOUR_ID
NODE_ENV=development

Development Workflow

[Edit local code] → [Auto-reload via tsx watch]
                          ↓
[Fire test webhook] → [Lindy agent processes]
                          ↓
[Agent calls back] → [ngrok tunnel → localhost:3000]
                          ↓
[Review logs] → [Iterate]

Error Handling

Issue	Cause	Solution
ngrok tunnel expires	Free tier limit (2hr)	Restart ngrok or use paid plan
Lindy can't reach endpoint	Tunnel URL changed	Update webhook URL in Lindy dashboard
Callback not received	Agent HTTP Request misconfigured	Check URL and headers in action config
ECONNREFUSED	Local server not running	Start server before testing
SSL error	ngrok not using HTTPS	Always use the https:// ngrok URL

Resources

• Webhook Triggers
• Calling Any API
• Lindy Documentation

Next Steps

Proceed to lindy-sdk-patterns for integration patterns and best practices.