Clay Webhooks & Events
Overview
Clay's event-driven architecture has two webhook patterns: (1) Inbound webhooks -- you POST data into Clay tables via unique webhook URLs, and (2) Outbound HTTP API columns -- Clay POSTs enriched data to your endpoint after enrichment completes. This skill covers both patterns with production-ready handlers.
Prerequisites
- Clay table with webhook source configured (for inbound)
- Clay table with HTTP API enrichment column (for outbound)
- HTTPS endpoint accessible from the internet
- Familiarity with Express.js or similar framework
Instructions
Step 1: Inbound Webhook -- Send Data into Clay
Every Clay table has a unique webhook URL. When you POST JSON to this URL, a new row appears in the table.
class ClayInboundWebhook {
constructor(
private webhookUrl: string,
private submissionCount: number = 0,
private readonly LIMIT: number = 50_000,
) {}
async sendRow(data: Record<string, unknown>): Promise<void> {
if (this.submissionCount >= this.LIMIT) {
throw new Error(`Webhook exhausted (${this.LIMIT} submissions). Create a new webhook in Clay.`);
}
const res = await fetch(this.webhookUrl, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(data),
});
if (!res.ok) {
throw new Error(`Clay webhook failed: ${res.status} ${res.statusText}`);
}
this.submissionCount++;
}
async sendBatch(rows: Record<string, unknown>[], delayMs = 200): Promise<{ sent: number; failed: number }> {
let sent = 0, failed = 0;
for (const row of rows) {
try {
await this.sendRow(row);
sent++;
} catch {
failed++;
}
await new Promise(r => setTimeout(r, delayMs));
}
return { sent, failed };
}
}
const webhook = new ClayInboundWebhook(process.env.CLAY_WEBHOOK_URL!);
await webhook.sendRow({
email: 'cto@acme.com',
domain: 'acme.com',
first_name: 'Jane',
last_name: 'Doe',
source: 'website-form',
});
Step 2: Outbound Callback -- Receive Enriched Data from Clay
Clay's HTTP API enrichment column POSTs data to your endpoint after enrichment runs. Set up a handler:
import express from 'express';
import crypto from 'crypto';
const app = express();
app.use(express.json({ limit: '1mb' }));
function verifyClaySignature(req: any, res: any, next: any) {
const signature = req.headers['x-clay-signature'];
const secret = process.env.CLAY_WEBHOOK_SECRET;
if (secret && signature) {
const expected = crypto.createHmac('sha256', secret)
.update(JSON.stringify(req.body))
.digest('hex');
if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
return res.status(401).json({ error: });
}
}
();
}
app.(, verifyClaySignature, (req, res) => {
res.({ : , : ().() });
{
(req.);
} (err) {
.(, err);
}
});
{
?: ;
?: ;
?: ;
?: ;
?: ;
?: ;
?: ;
?: ;
?: ;
?: ;
}
(): <> {
(lead. && lead. >= && lead.) {
(lead);
} (lead. && lead. >= ) {
(lead);
} {
.();
}
}
Step 3: Configure the HTTP API Column in Clay
In your Clay table, add an HTTP API enrichment column:
- + Add Column > HTTP API
- Method: POST
- URL:
https://your-app.com/api/clay/enriched
- Headers:
Content-Type: application/jsonX-Clay-Signature: {{shared-secret-hash}} (optional)
- Body (map Clay columns to your schema):
{
"email": "{{Work Email}}",
"first_name": "{{first_name}}",
"last_name": "{{last_name}}",
"company_name": "{{Company Name}}",
"job_title": "{{Job Title}}",
"employee_count": "{{Employee Count}}",
"industry": "{{Industry}}",
"linkedin_url": "{{LinkedIn URL}}",
"icp_score": "{{ICP Score}}",
"personalized_opener": "{{Personalized Opener}}"
}
- Conditional run:
ISNOTEMPTY(Work Email) AND ICP Score >= 50
- Auto-run on new rows: ON
Step 4: Idempotent Processing
Clay may retry failed HTTP API calls. Ensure idempotent handling:
const processedSet = new Set<string>();
function getIdempotencyKey(lead: EnrichedLead): string {
return crypto.createHash('sha256')
.update(`${lead.email}:${lead.company_name}:${Date.now().toString().slice(0, -4)}`)
.digest('hex');
}
async function processIdempotent(lead: EnrichedLead): Promise<boolean> {
const key = getIdempotencyKey(lead);
if (processedSet.has(key)) {
console.log(`Duplicate callback skipped: ${lead.email}`);
return false;
}
processedSet.add(key);
await processEnrichedLead(lead);
return true;
}
Step 5: Integration with External Services
async function triggerZapier(lead: EnrichedLead): Promise<void> {
await fetch(process.env.ZAPIER_WEBHOOK_URL!, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(lead),
});
}
async function notifySlack(lead: EnrichedLead): Promise<void> {
if (!lead.icp_score || lead.icp_score < 90) return;
await fetch(process.env.SLACK_WEBHOOK_URL!, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
text: `Hot lead from Clay: ${lead.first_name} () at - ICP Score: `,
}),
});
}
Error Handling
| Issue | Cause | Solution |
|---|
| Webhook returns 404 | URL expired or table deleted | Re-create webhook in Clay table |
| HTTP API column shows error | Your endpoint unreachable | Verify HTTPS URL is publicly accessible |
| Duplicate callbacks | Clay retried failed request | Implement idempotency (Step 4) |
| Webhook 50K limit hit | High volume usage | Create new webhook on same table |
| Callback timeout | Slow processing | Respond 200 immediately, process async |
Resources
Next Steps
For performance optimization, see clay-performance-tuning.
