Webhooks

Webhooks allow you to receive real-time notifications when events occur in ClarityCall, such as when a recording finishes processing or insights are generated.

Available Events

Event	Description
`recording.completed`	Recording processing completed successfully
`recording.failed`	Recording processing failed
`insights.ready`	AI insights have been generated for a recording
`contact.updated`	Contact profile was updated with new data

Webhook Payload

All webhook payloads follow this structure:

json

{
  "event": "recording.completed",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "recording_id": "550e8400-e29b-41d4-a716-446655440000",
    "filename": "team-standup.mp3",
    "status": "completed"
  }
}

Verifying Webhooks

All webhooks include an X-ClarityCall-Signature header containing an HMAC-SHA256 signature. Verify this signature to ensure the webhook is authentic.

javascript

import crypto from 'crypto';

function verifyWebhook(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

Retry Policy

If your webhook endpoint returns a non-2xx status code, we will retry the delivery:

1st retry: 1 minute after initial attempt
2nd retry: 5 minutes after 1st retry
3rd retry: 30 minutes after 2nd retry
4th retry: 2 hours after 3rd retry

After 4 failed attempts, the webhook will be marked as failed and no further retries will be made.