Webhooks

Delivery

• Method: POST with Content-Type: application/json
• Signature header: X-ClipSonar-Signature (HMAC-SHA256 hex of the raw body, using your whsec_… secret)
• Failed deliveries are retried with backoff. Respond with 2xx to acknowledge.
• Signing secrets use the whsec_… prefix. You can copy them anytime from Settings → API access.

Envelope

Every delivery uses the same outer shape:

{
  "event": "creator.ready",
  "created_at": "2026-08-04T14:00:00.000Z",
  "workspace_id": "grp_1111-2222-3333-4444",
  "data": {
    "creator_id": "354bb8ac-815d-4db1-8db8-ddf76c0f9494",
    "job_id": "82fde0d4-1111-2222-3333-444455556666"
  }
}

• event: event name
• created_at: ISO timestamp when ClipSonar emitted the event
• workspace_id: group scope when applicable, otherwise null
• data: event-specific payload

Events

{
  "creator_id": "…",
  "job_id": "…",
  "external_user_id": null,
  "metadata": null
}

{
  "creator_id": "…",
  "job_id": "…"
}

{
  "creator_id": "…",
  "job_id": "…",
  "error_message": "…"
}

{
  "clip_id": "…",
  "collection_id": "…",
  "workspace_id": "…",
  "external_user_id": null
}

{
  "account_id": "…"
}

{ }

Verify signatures

Always verify against the raw request body before parsing JSON. Compare with a timing-safe equality check.

const crypto = require('crypto');

function verifyClipSonarSignature(rawBody, signatureHeader, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader)
  );
}