OpenParable
Skip to content
← Back to skills

Clay Webhooks Events

Apps & Automation
clay-webhooks-events

Clay Webhooks Events is an Agent Skill for apps & automation published in the Dicklesworthstone/pi_agent_rust repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Implement Clay webhook signature validation and event handling. Use when setting up webhook endpoints, implementing signature verification, or handling Clay event notifications securely. Trigger with phrases like "clay webhook", "clay events", "clay webhook signature", "handle clay events", "clay notifications".

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/Dicklesworthstone/pi_agent_rust/blob/HEAD/tests/ext_conformance/artifacts/plugins-community/plugins/saas-packs/clay-pack/skills/clay-webhooks-events/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/clay-webhooks-events, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Clay Webhooks & Events

Overview

Securely handle Clay webhooks with signature validation and replay protection.

Prerequisites

  • Clay webhook secret configured
  • HTTPS endpoint accessible from internet
  • Understanding of cryptographic signatures
  • Redis or database for idempotency (optional)

Webhook Endpoint Setup

Express.js

import express from 'express';
import crypto from 'crypto';

const app = express();

// IMPORTANT: Raw body needed for signature verification
app.post('/webhooks/clay',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const signature = req.headers['x-clay-signature'] as string;
    const timestamp = req.headers['x-clay-timestamp'] as string;

    if (!verifyClaySignature(req.body, signature, timestamp)) {
      return res.status(401).json({ error: 'Invalid signature' });
    }

    const event = JSON.parse(req.body.toString());
    await handleClayEvent(event);

    res.status(200).json({ received: true });
  }
);

Signature Verification

function verifyClaySignature(
  payload: Buffer,
  signature: string,
  timestamp: string
): boolean {
  const secret = process.env.CLAY_WEBHOOK_SECRET!;

  // Reject old timestamps (replay attack protection)
  const timestampAge = Date.now() - parseInt(timestamp) * 1000;
  if (timestampAge > 300000) { // 5 minutes
    console.error('Webhook timestamp too old');
    return false;
  }

  // Compute expected signature
  const signedPayload = `${timestamp}.${payload.toString()}`;
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');

  // Timing-safe comparison
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

Event Handler Pattern

type ClayEventType = 'resource.created' | 'resource.updated' | 'resource.deleted';

interface ClayEvent {
  id: string;
  type: ClayEventType;
  data: Record<string, any>;
  created: string;
}

const eventHandlers: Record<ClayEventType, (data: any) => Promise<void>> = {
  'resource.created': async (data) => { /* handle */ },
  'resource.updated': async (data) => { /* handle */ },
  'resource.deleted': async (data) => { /* handle */ }
};

async function handleClayEvent(event: ClayEvent): Promise<void> {
  const handler = eventHandlers[event.type];

  if (!handler) {
    console.log(`Unhandled event type: ${event.type}`);
    return;
  }

  try {
    await handler(event.data);
    console.log(`Processed ${event.type}: ${event.id}`);
  } catch (error) {
    console.error(`Failed to process ${event.type}: ${event.id}`, error);
    throw error; // Rethrow to trigger retry
  }
}

Idempotency Handling

import { Redis } from 'ioredis';

const redis = new Redis(process.env.REDIS_URL);

async function isEventProcessed(eventId: string): Promise<boolean> {
  const key = `clay:event:${eventId}`;
  const exists = await redis.exists(key);
  return exists === 1;
}

async function markEventProcessed(eventId: string): Promise<void> {
  const key = `clay:event:${eventId}`;
  await redis.set(key, '1', 'EX', 86400 * 7); // 7 days TTL
}

Webhook Testing

# Use Clay CLI to send test events
clay webhooks trigger resource.created --url http://localhost:3000/webhooks/clay

# Or use webhook.site for debugging
curl -X POST https://webhook.site/your-uuid \
  -H "Content-Type: application/json" \
  -d '{"type": "resource.created", "data": {}}'

Instructions

Step 1: Register Webhook Endpoint

Configure your webhook URL in the Clay dashboard.

Step 2: Implement Signature Verification

Use the signature verification code to validate incoming webhooks.

Step 3: Handle Events

Implement handlers for each event type your application needs.

Step 4: Add Idempotency

Prevent duplicate processing with event ID tracking.

Output

  • Secure webhook endpoint
  • Signature validation enabled
  • Event handlers implemented
  • Replay attack protection active

Error Handling

IssueCauseSolution
Invalid signatureWrong secretVerify webhook secret
Timestamp rejectedClock driftCheck server time sync
Duplicate eventsMissing idempotencyImplement event ID tracking
Handler timeoutSlow processingUse async queue

Examples

Testing Webhooks Locally

# Use ngrok to expose local server
ngrok http 3000

# Send test webhook
curl -X POST https://your-ngrok-url/webhooks/clay \
  -H "Content-Type: application/json" \
  -d '{"type": "test", "data": {}}'

Resources

Next Steps

For performance optimization, see clay-performance-tuning.