Configure Clay local development with hot reload and testing.
Use when setting up a development environment, configuring test workflows,
or establishing a fast iteration cycle with Clay.
Trigger with phrases like "clay dev setup", "clay local development",
"clay dev environment", "develop with clay".
Clay is a web-based platform with no local runtime. Your local dev loop consists of: (1) scripts that push data into Clay via webhooks, (2) Clay enrichment running in the cloud, and (3) HTTP API columns pushing enriched data back to your local endpoint via ngrok. This skill sets up that feedback loop.
Prerequisites
Completed clay-install-auth setup
Node.js 18+ or Python 3.10+
ngrok installed (npm install -g ngrok or ngrok.com)
Clay table with webhook source configured
Instructions
Step 1: Expose Your Local Server via ngrok
Clay's HTTP API enrichment columns need a public URL to call your local endpoints.
# Start ngrok tunnel to your local server
ngrok http 3000
# Copy the HTTPS forwarding URL (e.g., https://abc123.ngrok-free.app)
Step 2: Create a Local Webhook Receiver
// src/clay-receiver.ts — receives enriched data from Clay HTTP API columns
import express from 'express';
const app = express();
app.use(express.json());
// Clay HTTP API column calls this endpoint
app.post('/api/clay/enriched', (req, res) => {
const enrichedData = req.body;
console.log('Enriched record received from Clay:', {
email: enrichedData.email,
company: enrichedData.company_name,
title: enrichedData.job_title,
enrichment_source: enrichedData._clay_source,
});
// Process the enriched data (save to DB, trigger outreach, etc.)
res.json({ status: 'received', timestamp: new Date().toISOString() });
});
// Health check for Clay HTTP API column testing
app.get('/api/health', (req, res) => {
res.json({ status: 'ok', service: 'clay-dev-receiver' });
});
app.listen(3000, () => {
console.log('Clay dev receiver listening on http://localhost:3000');
console.log('Configure Clay HTTP API column to POST to: <ngrok-url>/api/clay/enriched');
});
Step 3: Build a Test Data Sender
// src/send-test-leads.ts — push test data into Clay via webhook
const CLAY_WEBHOOK_URL = process.env.CLAY_WEBHOOK_URL!;
const testLeads = [
{ email: '[email protected]', domain: 'stripe.com', source: 'dev-test' },
{ email: '[email protected]', domain: 'notion.so', source: 'dev-test' },
{ email: '[email protected]', domain: 'figma.com', source: 'dev-test' },
];
async function sendTestBatch() {
for (const lead of testLeads) {
const res = await fetch(CLAY_WEBHOOK_URL, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(lead),
});
console.log(`Sent ${lead.email}: ${res.status}`);
await new Promise(r => setTimeout(r, 200)); // Respect rate limits
}
console.log('\nCheck your Clay table — enrichment columns should auto-run.');
console.log('Enriched data will POST back to your ngrok endpoint.');
}
sendTestBatch();
Step 4: Configure Clay HTTP API Column to Call You Back
In your Clay table:
Click + Add Column > HTTP API
Set Method: POST
Set URL: https://your-ngrok-url.ngrok-free.app/api/clay/enriched
Set Body (JSON): Map enriched columns using Clay's {{column_name}} syntax:
# Terminal 1: Run ngrok
ngrok http 3000
# Terminal 2: Run your local receiver
npx tsx src/clay-receiver.ts
# Terminal 3: Send test data to Clay
npx tsx src/send-test-leads.ts
# Watch Terminal 2 for enriched data flowing back from Clay
Iteration cycle:
Modify enrichment columns or Claygent prompts in Clay UI
