Webhooks

​

Overview

​

Webhook Events

• question.audio_generated - Question audio generation completed
• candidate_interview.completed - Candidate completed interview
• candidate_interview.status_changed - Status changed
• interview.created - Interview created
• interview.updated - Interview updated

​

Webhook Payload Format

{
  "event": "candidate_interview.completed",
  "timestamp": "2024-01-01T00:00:00Z",
  "data": {
    "candidateInterviewId": "uuid",
    "candidateId": "uuid",
    "interviewId": "uuid",
    "status": "new_response",
    "takenAt": "2024-01-01T00:00:00Z"
  }
}

​

Webhook Configuration

​

Configuration Options

• Multiple URLs: Supports multiple webhook URLs per organization
• Event Filtering: Configure which events to receive
• Retry Logic: Automatic retries with exponential backoff (3 attempts)
• Signature Verification: HMAC-SHA256 signature for security

​

Webhook Signature Verification

X-Qualifi-Signature: t=timestamp,v1=signature

​

Verification Process

1. Extract timestamp and signature from header
2. Create payload string: timestamp + "." + JSON.stringify(payload)
3. Compute HMAC-SHA256 using your webhook secret
4. Compare computed signature with provided signature

​

Example Verification

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const [timestamp, sig] = signature.split(',');
  const [_, timestampValue] = timestamp.split('=');
  const [__, signatureValue] = sig.split('=');
  
  const payloadString = `${timestampValue}.${JSON.stringify(payload)}`;
  const computedSignature = crypto
    .createHmac('sha256', secret)
    .update(payloadString)
    .digest('hex');
  
  return computedSignature === signatureValue;
}

import hmac
import hashlib
import json

def verify_webhook_signature(payload, signature, secret):
    timestamp, sig = signature.split(',')
    timestamp_value = timestamp.split('=')[1]
    signature_value = sig.split('=')[1]
    
    payload_string = f"{timestamp_value}.{json.dumps(payload)}"
    computed_signature = hmac.new(
        secret.encode(),
        payload_string.encode(),
        hashlib.sha256
    ).hexdigest()
    
    return computed_signature == signature_value

​

Event Details

​

question.audio_generated

{
  "event": "question.audio_generated",
  "timestamp": "2024-01-01T00:00:00Z",
  "data": {
    "questionId": "uuid",
    "audioUrl": "https://...",
    "status": "completed"
  }
}

​

candidate_interview.completed

{
  "event": "candidate_interview.completed",
  "timestamp": "2024-01-01T00:00:00Z",
  "data": {
    "candidateInterviewId": "uuid",
    "candidateId": "uuid",
    "interviewId": "uuid",
    "status": "new_response",
    "takenAt": "2024-01-01T00:00:00Z"
  }
}

​

candidate_interview.status_changed

{
  "event": "candidate_interview.status_changed",
  "timestamp": "2024-01-01T00:00:00Z",
  "data": {
    "candidateInterviewId": "uuid",
    "oldStatus": "invite_sent",
    "newStatus": "new_response"
  }
}

​

Retry Logic

1. First attempt: Immediate
2. Second attempt: After 1 minute
3. Third attempt: After 5 minutes

​

Best Practices

1. Verify Signatures: Always verify webhook signatures to ensure authenticity
2. Idempotency: Handle duplicate webhook deliveries gracefully
3. Quick Response: Respond to webhooks quickly (within 5 seconds)
4. Error Handling: Return appropriate HTTP status codes
5. Logging: Log all webhook events for debugging

​

Related Resources