Webhooks

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

Open Settings > API - Navigate to Settings > API in your clarife dashboard.
Click 'Add webhook' - Enter your endpoint URL (must be HTTPS) and select the events you want to subscribe to.
Copy the signing secret - Each subscription gets a unique signing secret. Copy it and store it securely - you will use it to verify payloads.
Activate - Your webhook starts receiving events immediately.

Subscription Limits

Plan	Max Subscriptions
Pro	3
Business	20

Event Types

Event	Description
document.created	A new document was created
document.updated	A document's title, description, or content changed
document.deleted	A document was soft-deleted (moved to trash)
project.created	A new project was created
project.updated	A project was renamed or moved
project.deleted	A project was deleted
project.moved	A project was moved to a different folder
folder.created	A new folder was created
folder.updated	A folder was renamed
folder.deleted	A folder was deleted
media.uploaded	A media file was uploaded and confirmed
generation.completed	An AI video generation finished
share.created	A share link was created
share.viewed	A share link was viewed
share.updated	A share link's settings were changed
share.deleted	A share link was deleted
workspace.member_added	A member was added to the workspace
workspace.member_removed	A member was removed from the workspace

Payload Format

Every webhook delivery sends a JSON POST request with this structure, along with the X-Clarife-Event (event type) and X-Clarife-Delivery (delivery ID) headers:

json

{
  "id": "evt_a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "event": "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 details of the resource at the time of the event.

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 string timestamp.deliveryId.body, computed with your webhook signing secret. deliveryId is the value of the X-Clarife-Delivery header (equal to the id field in the body).

Node.js Verification Example

javascript

import crypto from "crypto";

function verifyWebhookSignature(rawBody, signature, deliveryId, 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(`${timestamp}.${deliveryId}.${rawBody}`)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(receivedHmac, "hex"),
    Buffer.from(expectedHmac, "hex")
  );
}

⚠️ Warning: Always verify the signature before processing a webhook. Compute the HMAC over the raw request body (do not re-serialize the JSON) and 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:

Attempt	Delay
1st retry	1 second
2nd retry	5 seconds
3rd retry	15 seconds

After these attempts fail, the delivery is marked as failed. Failed events are additionally retried periodically by a background job.

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 test.ping event to your endpoint. This helps you verify that your server receives and processes payloads correctly without waiting for a real event.

💡 Tip: During development, use a tunnel service like ngrok or Cloudflare Tunnel to expose your local server to the internet.