Clay Integration Patterns
Overview
Production-ready patterns for Clay integrations. Clay does not have an official SDK -- you interact via webhooks (inbound), HTTP API enrichment columns (outbound from Clay), and the Enterprise API (programmatic lookups). These patterns wrap those interfaces into reliable, reusable code.
Prerequisites
- Completed
clay-install-auth setup
- Familiarity with async/await patterns
- Understanding of Clay's webhook and HTTP API model
Instructions
Step 1: Create a Clay Webhook Client (TypeScript)
interface ClayConfig {
webhookUrl: string;
enterpriseApiKey?: string;
baseUrl?: string;
maxRetries?: number;
timeoutMs?: number;
}
class ClayClient {
private config: Required<ClayConfig>;
constructor(config: ClayConfig) {
this.config = {
baseUrl: 'https://api.clay.com',
maxRetries: 3,
timeoutMs: 30_000,
enterpriseApiKey: '',
...config,
};
}
async sendToTable(data: Record<string, unknown>): Promise<void> {
const res = await this.fetchWithRetry(this.config.webhookUrl, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(data),
});
if (!res.ok) {
throw new ClayWebhookError(`Webhook failed: ${res.status}`, res.status);
}
}
async sendBatch(rows: Record<string, unknown>[], delayMs = 200): Promise<BatchResult> {
const results: BatchResult = { sent: 0, failed: 0, errors: [] };
for (const row of rows) {
try {
await this.sendToTable(row);
results.sent++;
} catch (err) {
results.failed++;
results.errors.push({ row, error: (err as Error).message });
}
if (delayMs > 0) await new Promise(r => setTimeout(r, delayMs));
}
return results;
}
async enrichPerson(email: string): Promise<PersonEnrichment> {
if (!this.config.enterpriseApiKey) {
throw new Error('Enterprise API key required for person enrichment');
}
const res = await this.fetchWithRetry(`${this.config.baseUrl}/v1/people/enrich`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${this.config.enterpriseApiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ email }),
});
return res.json();
}
async enrichCompany(domain: string): Promise<CompanyEnrichment> {
if (!this.config.enterpriseApiKey) {
throw new Error('Enterprise API key required for company enrichment');
}
const res = await this.fetchWithRetry(`${this.config.baseUrl}/v1/companies/enrich`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${this.config.enterpriseApiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ domain }),
});
return res.json();
}
private async fetchWithRetry(url: string, init: RequestInit): Promise<Response> {
for (let attempt = 0; attempt <= this.config.maxRetries; attempt++) {
try {
const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), this.config.timeoutMs);
const res = await fetch(url, { ...init, signal: controller.signal });
clearTimeout(timeout);
if (res.status === 429) {
const retryAfter = parseInt(res.headers.get('Retry-After') || '5');
await new Promise(r => setTimeout(r, retryAfter * 1000));
continue;
}
return res;
} catch (err) {
if (attempt === this.config.maxRetries) throw err;
await new Promise(r => setTimeout(r, 1000 * Math.pow(2, attempt)));
}
}
throw new Error('Max retries exceeded');
}
}
Step 2: Type Definitions for Clay Data
interface PersonEnrichment {
name?: string;
email?: string;
title?: string;
company?: string;
linkedin_url?: string;
location?: string;
}
interface CompanyEnrichment {
name?: string;
domain?: string;
industry?: string;
employee_count?: number;
linkedin_url?: string;
location?: string;
description?: string;
}
interface BatchResult {
sent: number;
failed: number;
errors: Array<{ row: Record<string, unknown>; error: string }>;
}
class ClayWebhookError extends Error {
constructor(message: string, public : ) {
(message);
. = ;
}
}
Step 3: Python Client
import httpx
import asyncio
from dataclasses import dataclass, field
from typing import Any
@dataclass
class ClayClient:
webhook_url: str
enterprise_api_key: str = ""
base_url: str = "https://api.clay.com"
max_retries: int = 3
timeout: float = 30.0
async def send_to_table(self, data: dict[str, Any]) -> None:
"""Send a single record to a Clay table via webhook."""
async with httpx.AsyncClient(timeout=self.timeout) as client:
for attempt in range(self.max_retries + 1):
response = await client.post(
self.webhook_url,
json=data,
headers={"Content-Type": "application/json"},
)
if response.status_code == 429:
retry_after = int(response.headers.get("Retry-After", ))
asyncio.sleep(retry_after)
response.raise_for_status()
Exception()
() -> :
results = {: , : , : []}
row rows:
:
.send_to_table(row)
results[] +=
Exception e:
results[] +=
results[].append({: row, : (e)})
asyncio.sleep(delay)
results
() -> :
httpx.AsyncClient(timeout=.timeout) client:
response = client.post(
,
json={: email},
headers={: },
)
response.raise_for_status()
response.json()
Step 4: Singleton Pattern for Multi-Use
let instance: ClayClient | null = null;
export function getClayClient(): ClayClient {
if (!instance) {
instance = new ClayClient({
webhookUrl: process.env.CLAY_WEBHOOK_URL!,
enterpriseApiKey: process.env.CLAY_API_KEY,
});
}
return instance;
}
Error Handling
| Pattern | Use Case | Benefit |
|---|
| Retry with backoff | 429 rate limits, network errors | Automatic recovery |
| Batch with delay | Sending many rows | Respects Clay rate limits |
| Enterprise API guard | Missing API key | Clear error before API call |
| Timeout control | Slow webhook delivery | Prevents hung connections |
Examples
Webhook Handler for Clay Callbacks
app.post('/api/clay/callback', (req, res) => {
res.json({ ok: true });
processEnrichedData(req.body).catch(console.error);
});
Resources
Next Steps
Apply patterns in clay-core-workflow-a for real-world lead enrichment.
