Clay Webhooks & Events

Overview

Handle Clay webhooks for real-time notifications when data enrichment completes, tables update, or workflows finish. Respond 200 immediately and process events asynchronously.

Prerequisites

• Clay account with API access and webhook configuration enabled

• HTTPS endpoint accessible from the internet

• Clay API key stored in CLAY_API_KEY environment variable

• Familiarity with Clay table and enrichment concepts

Webhook Event Types

Event Trigger Payload

enrichment.completed

Column enrichment finishes Row data, enrichment results

enrichment.failed

Enrichment errors out Row ID, error details

table.row.created

New row added to table Full row data

table.row.updated

Row data changes Changed fields, row ID

table.export.completed

Table export finishes Export URL, row count

workflow.completed

Automated workflow ends Workflow ID, results summary

Instructions

Step 1: Configure Webhook Endpoint

Create an Express endpoint that validates the x-clay-signature header using HMAC-SHA256 with crypto.timingSafeEqual . Respond 200 before processing.

Step 2: Route Events by Type

Switch on payload.event to dispatch to specific handlers for enrichment completion, failures, new rows, and exports.

Step 3: Handle Enrichment Results

On enrichment.completed , push enriched data (company info, LinkedIn data) to your CRM. On enrichment.failed , queue for retry with the error details.

Step 4: Register Webhook via Clay API

POST to https://api.clay.com/v1/webhooks with your endpoint URL, desired event types, and table ID.

For complete TypeScript implementations and curl examples, load the reference guide: Read(${CLAUDE_SKILL_DIR}/references/implementation-guide.md)

Error Handling

Issue Cause Solution

Invalid signature Wrong webhook secret Verify secret in Clay dashboard settings

Missing enrichment data Column not configured Check enrichment column setup in table

Duplicate events Retry delivery Track row_id + timestamp for idempotency

Webhook timeout Slow handler Respond 200 immediately, process async

Resources

• Clay API Documentation

• Clay Webhooks Guide

Next Steps

For performance optimization, see clay-performance-tuning .

Output

• Configuration files or code changes applied to the project

• Validation report confirming correct implementation

• Summary of changes made and their rationale

See Clay Webhooks Events implementation details for output format specifications.

Examples

Basic usage: Apply clay webhooks events to a standard project setup with default configuration options.

Advanced scenario: Customize clay webhooks events for production environments with multiple constraints and team-specific requirements.