Skip to main content

​
Overview

Webhooks let your server receive HTTP POST requests whenever something changes in your clarife workspace. Use them to sync data, trigger workflows, or build real-time integrations.

​
Setting Up Webhooks

1

Open Settings > API

Navigate to Settings > API in your clarife dashboard.
2

Click 'Add webhook'

Enter your endpoint URL (must be HTTPS) and select the events you want to subscribe to.
3

Copy the signing secret

Each subscription gets a unique signing secret. Copy it and store it securely — you will use it to verify payloads.
4

Activate

Your webhook starts receiving events immediately.

​
Subscription Limits

PlanMax Subscriptions
Pro3
Business20

​
Event Types

EventDescription
document.createdA new document was created
document.updatedA document’s title, description, or content changed
document.deletedA document was soft-deleted (moved to trash)
project.createdA new project was created
project.updatedA project was renamed or moved
project.deletedA project was deleted
folder.createdA new folder was created
folder.updatedA folder was renamed
folder.deletedA folder was deleted
media.uploadedA media file was uploaded and confirmed
generation.startedAn AI video generation started
generation.completedAn AI video generation finished successfully
generation.failedAn AI video generation failed
share.createdA share link was created
share.updatedA share link’s settings were changed
share.deletedA share link was deleted

​
Payload Format

Every webhook delivery sends a JSON POST request with this structure: 
{
  "id": "evt_a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "type": "document.updated",
  "created_at": "2026-03-28T12:00:00Z",
  "data": {
    "id": "d1a2b3c4-...",
    "title": "Updated Document",
    "updated_at": "2026-03-28T12:00:00Z"
  }
}
The data field contains the relevant resource at the time of the event. Its shape matches the corresponding API response for that resource type.

​
Signature Verification

Every webhook request includes an X-Clarife-Signature header for authenticity verification: 
X-Clarife-Signature: t=1711612800,v1=5a2f...c9e1
The signature is an HMAC-SHA256 hash of the raw JSON payload, computed using your webhook signing secret.

​
Node.js Verification Example

import crypto from "crypto";

function verifyWebhookSignature(payload, signature, secret) {
  const [tPart, v1Part] = signature.split(",");
  const timestamp = tPart.replace("t=", "");
  const receivedHmac = v1Part.replace("v1=", "");

  // Reject if timestamp is older than 5 minutes
  const age = Date.now() / 1000 - parseInt(timestamp);
  if (age > 300) return false;

  const expectedHmac = crypto
    .createHmac("sha256", secret)
    .update(JSON.stringify(payload))
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(receivedHmac, "hex"),
    Buffer.from(expectedHmac, "hex")
  );
}
Always verify the signature before processing a webhook. Use timing-safe comparison to prevent timing attacks.

​
Retry Policy

If your endpoint returns a non-2xx status code or times out (10 second limit), clarife retries the delivery:
AttemptDelay
1st retry1 second
2nd retry10 seconds
3rd retry60 seconds
After 3 failed attempts, the delivery is marked as failed.

​
Auto-Deactivation

If a webhook subscription accumulates 10 consecutive failures (across any deliveries, not just retries of a single event), clarife automatically deactivates it. You will see a warning in your dashboard. To reactivate, fix the issue with your endpoint and toggle the subscription back on in Settings > API.

​
Testing Webhooks

Use the Send test event button in your webhook settings to send a synthetic event to your endpoint. This helps you verify that your server receives and processes payloads correctly without waiting for a real event.
During development, use a tunnel service like ngrok or Cloudflare Tunnel to expose your local server to the internet.