SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场clay-deploy-integration

clay-deploy-integration

部署与运维

查看项目

更新于 10-16 09:08

技能介绍

用途

Clay Deploy Integration 用于把与 Clay 集成的应用部署到生产平台。Clay 本身是托管 SaaS，因此部署的对象是与其交互的代码，例如 webhook 接收器、数据丰富处理器、CRM 同步服务。关键要求是提供一个可公开访问的 HTTPS 端点，供 Clay 的 HTTP API 列回调。

主要能力

  • 支持三种部署目标：Vercel（无服务器）、Cloud Run（容器）、Docker Compose（自托管）。
  • 提供各平台的部署命令与密钥注入方式。
  • 提供 webhook 签名校验示例（HMAC-SHA256 与 timingSafeEqual）。
  • 提供健康检查端点示例，验证服务器、Clay webhook 与数据库连通性。
  • 列出生产环境变量，区分必需项与可选（企业版）项。
  • 给出常见错误的原因与解决方案。

使用方式

前置条件

  • 处理 Clay webhook 或 HTTP API 回调的应用代码。
  • 已安装平台 CLI（vercel、gcloud 或 docker）。
  • 安全存储 Clay webhook URL 和/或 API key。
  • 可从公网访问的 HTTPS 端点。

步骤 1：Vercel 部署（无服务器）

适用：webhook 接收器、小规模数据丰富处理器。

# Set Clay secrets in Vercel
vercel env add CLAY_WEBHOOK_URL production
vercel env add CLAY_API_KEY production
vercel env add CLAY_WEBHOOK_SECRET production

# Deploy
vercel --prod

// api/clay/callback.ts — Vercel serverless function
import type { VercelRequest, VercelResponse } from '@vercel/node';
import crypto from 'crypto';

export default async function handler(req: VercelRequest, res: VercelResponse) {
  if (req.method !== 'POST') return res.status(405).end();

  // Validate webhook signature
  const signature = req.headers['x-clay-signature'] as string;
  const secret = process.env.CLAY_WEBHOOK_SECRET!;
  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: 'Invalid signature' });
  }

  // Process enriched data from Clay HTTP API column
  const enrichedLead = req.body;
  console.log('Received enriched lead:', {
    email: enrichedLead.email,
    company: enrichedLead.company_name,
    score: enrichedLead.icp_score,
  });

  // Push to CRM, database, or outreach tool
  await processLead(enrichedLead);

  return res.status(200).json({ status: 'processed' });
}

步骤 2：Cloud Run 部署（容器）

适用：高吞吐数据丰富流水线、CRM 同步服务。

# Dockerfile
FROM node:20-slim
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY dist/ ./dist/
EXPOSE 8080
ENV PORT=8080
CMD ["node", "dist/index.js"]

# Build and deploy to Cloud Run
gcloud builds submit --tag gcr.io/$PROJECT_ID/clay-handler

gcloud run deploy clay-handler \
  --image gcr.io/$PROJECT_ID/clay-handler \
  --platform managed \
  --region us-central1 \
  --allow-unauthenticated \
  --set-secrets "CLAY_API_KEY=clay-api-key:latest,CLAY_WEBHOOK_SECRET=clay-webhook-secret:latest" \
  --min-instances 1 \
  --max-instances 10

步骤 3：Docker Compose（自托管）

适用：本地部署、开发预发布环境。

# docker-compose.yml
version: '3.8'
services:
  clay-handler:
    build: .
    ports:
      - "3000:3000"
    environment:
      - CLAY_WEBHOOK_URL=${CLAY_WEBHOOK_URL}
      - CLAY_API_KEY=${CLAY_API_KEY}
      - CLAY_WEBHOOK_SECRET=${CLAY_WEBHOOK_SECRET}
      - DATABASE_URL=${DATABASE_URL}
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 30s
      timeout: 10s
      retries: 3

步骤 4：配置 Clay 调用已部署端点

  1. 获取部署 URL（例如 https://clay-handler.vercel.app 或 Cloud Run URL）。
  2. 在 Clay 表中编辑 HTTP API 列。
  3. 将 URL 设为：https://your-deployment.com/api/clay/callback。
  4. 先在单行上测试，再启用自动运行。

步骤 5：健康检查端点

// src/health.ts — health check that verifies Clay connectivity
app.get('/health', async (req, res) => {
  const checks: Record<string, string> = {
    server: 'ok',
    clay_webhook: 'unknown',
    database: 'unknown',
  };

  // Check Clay webhook reachability
  try {
    const webhookTest = await fetch(process.env.CLAY_WEBHOOK_URL!, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ _health_check: true }),
    });
    checks.clay_webhook = webhookTest.ok ? 'ok' : `error: ${webhookTest.status}`;
  } catch {
    checks.clay_webhook = 'unreachable';
  }

  const allHealthy = Object.values(checks).every(v => v === 'ok');
  res.status(allHealthy ? 200 : 503).json({ status: allHealthy ? 'healthy' : 'degraded', checks });
});

步骤 6：生产环境变量

# Required for all deployments
CLAY_WEBHOOK_URL=https://app.clay.com/api/v1/webhooks/your-id
CLAY_WEBHOOK_SECRET=your-shared-secret

# Optional (Enterprise only)
CLAY_API_KEY=clay_ent_your_key

# Application-specific
DATABASE_URL=postgresql://...
CRM_API_KEY=your-crm-key
PORT=3000

适用场景

  • 部署 Clay webhook 接收器。
  • 部署数据丰富处理器。
  • 部署 CRM 同步服务。
  • 需要将 Clay 集成代码发布到 Vercel、Cloud Run 或 Docker 的场景。

限制与注意事项

  • Clay 本身是托管 SaaS，不能部署 Clay 自身，只能部署与其交互的代码。
  • 必须提供可公开访问的 HTTPS 端点。
  • 输出部署回执时，不得在应用日志、CI 输出或回执中泄露 webhook URL、共享密钥、单条线索载荷或 CRM 凭据。
  • 示例中 CLAY_API_KEY 标注为可选（仅企业版）。

错误处理

问题 原因 解决方案
Clay 无法访问回调 端点非公开 HTTPS 验证 URL 可访问，检查防火墙
冷启动超时 无服务器函数过慢 在 Cloud Run 设置 min-instances=1
部署时缺少密钥 未配置环境变量 部署前通过平台 CLI 添加
健康检查失败 Clay webhook URL 无效 从 Clay 表重新复制 webhook URL

输出要求

发布包含环境、发布/版本、运行时标识、密钥引用、webhook 验证、健康检查、告警路由和回滚决策的部署回执。不要在应用日志、CI 输出或回执中输出 webhook URL、共享密钥、单条线索载荷或 CRM 凭据。

示例

使用专用运行时角色部署预发布回调，提交一条合成行，验证签名/授权回执、排队处理和脱敏健康结果。仅当生产环境门禁批准相同证据后才晋级；若出现可达性或密钥失败，应回滚发布，而不是开放端点或扩大其权限。

资源

  • Vercel Serverless Functions
  • Cloud Run Documentation
  • Clay University -- HTTP API Integration

后续步骤

关于 webhook 处理模式，参见 clay-webhooks-events。