Webhooks - ClypAI

Planned Feature - Webhooks are planned for ClypAI’s 2026 launch. The documentation below represents the intended design and may change before release.

Overview

Webhooks allow you to receive HTTP notifications when events occur in your ClypAI account. Instead of polling the API for changes, ClypAI will push notifications to your server in real-time.

Webhook endpoints require authentication. See Authentication for details.

Webhook Events

ClypAI supports the following webhook events:

Clip Events

clip.created

Triggered when a new clip is created

clip.processing

Triggered when clip processing starts

clip.completed

Triggered when clip generation completes successfully

clip.failed

Triggered when clip generation fails

clip.exported

Triggered when a clip is exported

clip.deleted

Triggered when a clip is deleted

Project Events

project.created

Triggered when a new project is created

project.updated

Triggered when a project is updated

project.deleted

Triggered when a project is deleted

Brand Kit Events

brand_kit.created

Triggered when a brand kit is created

brand_kit.updated

Triggered when a brand kit is updated

brand_kit.deleted

Triggered when a brand kit is deleted

Webhook Payload

All webhook events follow a consistent payload structure:

{
  "id": "evt_1a2b3c4d5e6f",
  "type": "clip.completed",
  "createdAt": "2024-01-15T10:35:22Z",
  "data": {
    // Event-specific data
  },
  "organizationId": "org_1234567890"
}

string

Unique identifier for the event (for deduplication)

type

string

The event type (e.g., clip.completed)

createdAt

string

ISO 8601 timestamp of when the event occurred

data

object

Event-specific payload data

organizationId

string

ID of the organization this event belongs to

Example Payloads

clip.completed

{
  "id": "evt_1a2b3c4d5e6f",
  "type": "clip.completed",
  "createdAt": "2024-01-15T10:35:22Z",
  "data": {
    "clip": {
      "id": "clip_xyz789abc",
      "projectId": "proj_a1b2c3d4e5",
      "name": "Product Demo Highlight",
      "status": "completed",
      "duration": 45.2,
      "outputs": {
        "videoUrl": "https://storage.clypai.com/clips/clip_xyz789abc.mp4",
        "thumbnailUrl": "https://storage.clypai.com/thumbnails/clip_xyz789abc.jpg"
      },
      "metadata": {
        "hooks": [
          {"time": 2.3, "text": "Watch this amazing feature", "confidence": 0.92}
        ],
        "sentiment": "positive"
      }
    }
  },
  "organizationId": "org_1234567890"
}

clip.failed

{
  "id": "evt_2b3c4d5e6f7g",
  "type": "clip.failed",
  "createdAt": "2024-01-15T10:40:15Z",
  "data": {
    "clip": {
      "id": "clip_abc123xyz",
      "projectId": "proj_a1b2c3d4e5",
      "name": "Failed Clip",
      "status": "failed"
    },
    "error": {
      "code": "processing_failed",
      "message": "Unsupported video codec",
      "details": {
        "codec": "h265"
      }
    }
  },
  "organizationId": "org_1234567890"
}

project.created

{
  "id": "evt_3c4d5e6f7g8h",
  "type": "project.created",
  "createdAt": "2024-01-15T09:15:00Z",
  "data": {
    "project": {
      "id": "proj_a1b2c3d4e5",
      "name": "Product Launch Campaign",
      "description": "Video clips for Q1 2024 product launch",
      "status": "active",
      "createdAt": "2024-01-15T09:15:00Z"
    }
  },
  "organizationId": "org_1234567890"
}

Creating Webhook Endpoints

Register a Webhook

curl -X POST https://api.clypai.com/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks/clypai",
    "events": ["clip.completed", "clip.failed"],
    "description": "Production webhook endpoint"
  }'

Parameters

url

string

required

The HTTPS URL where webhook events will be sent

events

array

required

Array of event types to subscribe to. Use ["*"] for all events.

description

string

Optional description to identify this webhook

secret

string

Optional webhook secret for signature verification. If not provided, one will be generated.

Response

{
  "success": true,
  "data": {
    "id": "webhook_1a2b3c4d",
    "url": "https://your-server.com/webhooks/clypai",
    "events": ["clip.completed", "clip.failed"],
    "description": "Production webhook endpoint",
    "secret": "whsec_a1b2c3d4e5f6g7h8i9j0",
    "status": "active",
    "createdAt": "2024-01-15T10:00:00Z"
  }
}

Store the webhook secret securely. You’ll need it to verify webhook signatures.

List Webhooks

curl https://api.clypai.com/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "data": [
    {
      "id": "webhook_1a2b3c4d",
      "url": "https://your-server.com/webhooks/clypai",
      "events": ["clip.completed", "clip.failed"],
      "description": "Production webhook endpoint",
      "status": "active",
      "createdAt": "2024-01-15T10:00:00Z"
    }
  ]
}

Delete Webhook

curl -X DELETE https://api.clypai.com/v1/webhooks/webhook_1a2b3c4d \
  -H "Authorization: Bearer YOUR_API_KEY"

Implementing Webhook Handlers

Basic Handler Example

const express = require('express');
const crypto = require('crypto');

const app = express();
app.use(express.json());

app.post('/webhooks/clypai', (req, res) => {
  const signature = req.headers['x-clypai-signature'];
  const payload = JSON.stringify(req.body);
  
  // Verify signature
  const expectedSignature = crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(payload)
    .digest('hex');
  
  if (signature !== expectedSignature) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process event
  const event = req.body;
  
  switch (event.type) {
    case 'clip.completed':
      console.log('Clip completed:', event.data.clip.id);
      // Your processing logic here
      break;
      
    case 'clip.failed':
      console.log('Clip failed:', event.data.clip.id, event.data.error);
      // Your error handling logic here
      break;
      
    default:
      console.log('Unhandled event type:', event.type);
  }
  
  // Acknowledge receipt
  res.status(200).json({ received: true });
});

app.listen(3000);

Signature Verification

All webhook requests include an X-ClypAI-Signature header for security. Verify this signature to ensure the request came from ClypAI.

Retrieve the Secret

Get your webhook secret from the webhook creation response or dashboard

Compute HMAC

Compute HMAC-SHA256 of the raw request body using your secret

Compare Signatures

Compare the computed signature with the X-ClypAI-Signature header

Verification Example

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
    
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

Best Practices

Respond Quickly

Return a 200 response within 5 seconds to acknowledge receipt. Process events asynchronously.

Handle Duplicates

Use the event id field to detect and handle duplicate deliveries.

Verify Signatures

Always verify the webhook signature to ensure authenticity.

Use HTTPS

Webhook URLs must use HTTPS for security.

Retry Policy

If your webhook endpoint fails or doesn’t respond within 5 seconds, ClypAI will retry:

First Retry

After 1 minute

Second Retry

After 5 minutes

Third Retry

After 15 minutes

Final Retry

After 1 hour

After 4 failed attempts, the webhook will be marked as failed and no further retries will be attempted for that event.

Testing Webhooks

Use tools like ngrok or webhook.site to test webhooks locally:

# Start ngrok to expose localhost:3000
ngrok http 3000

# Use the ngrok URL as your webhook endpoint
# Example: https://abc123.ngrok.io/webhooks/clypai

Error Responses

Invalid URL

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "Webhook URL must use HTTPS",
    "field": "url"
  }
}

Invalid Event Type

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "Invalid event type: invalid.event",
    "field": "events"
  }
}

Getting Started

Endpoints

​Overview

​Webhook Events

​Clip Events

clip.created

clip.processing

clip.completed

clip.failed

clip.exported

clip.deleted

​Project Events

project.created

project.updated

project.deleted

​Brand Kit Events

brand_kit.created

brand_kit.updated

brand_kit.deleted

​Webhook Payload

​Example Payloads

​clip.completed

​clip.failed

​project.created

​Creating Webhook Endpoints

​Register a Webhook

​Parameters

​Response

​List Webhooks

​Response

​Delete Webhook

​Implementing Webhook Handlers

​Basic Handler Example

​Signature Verification

​Verification Example

​Best Practices

Respond Quickly

Handle Duplicates

Verify Signatures

Use HTTPS

​Retry Policy

​Testing Webhooks

​Error Responses

​Invalid URL

​Invalid Event Type

Build docs developers (and LLMs) love

Overview

Webhook Events

Clip Events

Project Events

Brand Kit Events

Webhook Payload

Example Payloads

clip.completed

clip.failed

project.created

Creating Webhook Endpoints

Register a Webhook

Parameters

Response

List Webhooks

Response

Delete Webhook

Implementing Webhook Handlers

Basic Handler Example

Signature Verification

Verification Example

Best Practices

Retry Policy

Testing Webhooks

Error Responses

Invalid URL

Invalid Event Type