Handling Webhooks

Overview

Webhooks allow you to receive real-time notifications when events occur in the Gather API. This guide walks you through setting up and handling webhooks.

Setting Up Webhooks

Webhooks are configured per organization/team via the Gather API’s webhook configuration endpoints (/qsi/gather/webhooks — create, list, get, update, delete). See the Webhooks API reference for events and delivery details.

Configuration Requirements

Webhook URL: Your endpoint URL that will receive webhook events
Event Types: Which events you want to receive
Webhook Secret: Secret key for signature verification

Webhook Endpoint Setup

Your webhook endpoint should:

Accept POST requests
Respond quickly (within 5 seconds)
Return appropriate HTTP status codes
Verify webhook signatures

Basic Endpoint Structure

JavaScript (Express)
Python (Flask)

const express = require('express');
const crypto = require('crypto');
const app = express();

const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET;

// Use raw body for signature verification
app.use(express.json({
  verify: (req, res, buf) => {
    req.rawBody = buf;
  }
}));

function verifySignature({ rawBody, signature }) {
  const computedSignature = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(rawBody)
    .digest('hex');

  if (!signature || signature.length !== computedSignature.length) {
    return false;
  }
  return crypto.timingSafeEqual(
    Buffer.from(computedSignature),
    Buffer.from(signature)
  );
}

app.post('/webhooks/qualifi', (req, res) => {
  const signature = req.headers['x-qualifi-signature'];
  const event = req.headers['x-qualifi-event'];
  
  if (!verifySignature({ rawBody: req.rawBody, signature })) {
    return res.status(401).send('Invalid signature');
  }
  
  const payload = req.body;
  
  switch (event) {
    case 'candidate_interview.completed':
      handleInterviewCompleted(payload);
      break;
    case 'candidate_interview.status_changed':
      handleStatusChanged(payload);
      break;
    case 'question.audio_generated':
      handleAudioGenerated(payload);
      break;
    // ... other events
  }
  
  res.status(200).send('OK');
});

function handleInterviewCompleted(payload) {
  console.log('Interview completed:', payload.candidateInterviewId);
  // Process the completed interview
}

function handleStatusChanged(payload) {
  console.log('Status changed:', payload.candidateInterviewId, payload.status);
}

app.listen(3000);

from flask import Flask, request, jsonify
import hmac
import hashlib
import os

app = Flask(__name__)
WEBHOOK_SECRET = os.environ.get('WEBHOOK_SECRET')

def verify_signature(raw_body: bytes, signature: str) -> bool:
    computed_signature = hmac.new(
        WEBHOOK_SECRET.encode(),
        raw_body,
        hashlib.sha256
    ).hexdigest()
    
    return hmac.compare_digest(computed_signature, signature)

@app.route('/webhooks/qualifi', methods=['POST'])
def webhook():
    signature = request.headers.get('X-Qualifi-Signature')
    event = request.headers.get('X-Qualifi-Event')
    
    if not verify_signature(request.get_data(), signature):
        return jsonify({'error': 'Invalid signature'}), 401
    
    payload = request.get_json()
    
    if event == 'candidate_interview.completed':
        handle_interview_completed(payload)
    elif event == 'candidate_interview.status_changed':
        handle_status_changed(payload)
    elif event == 'question.audio_generated':
        handle_audio_generated(payload)
    
    return jsonify({'status': 'OK'}), 200

def handle_interview_completed(payload):
    print(f"Interview completed: {payload['candidateInterviewId']}")

def handle_status_changed(payload):
    print(f"Status changed: {payload['candidateInterviewId']} -> {payload['status']}")

if __name__ == '__main__':
    app.run(port=3000)

Verifying the Timestamped Signature (recommended)

Every delivery includes X-Qualifi-Timestamp and X-Qualifi-Signature-V2 (formatted t=<timestamp>,v1=<hex>), where the signature is computed over "<timestamp>.<rawBody>". Prefer this over the deprecated X-Qualifi-Signature header because the signed timestamp lets you reject replayed deliveries within a tolerance window (recommended: 5 minutes).

JavaScript (Express)
Python (Flask)

const TOLERANCE_SECONDS = 300; // 5 minutes

function verifySignatureV2({ rawBody, signatureHeader }) {
  const parts = Object.fromEntries(
    signatureHeader.split(',').map((kv) => kv.split('='))
  );
  const timestamp = Number(parts.t);
  const now = Math.floor(Date.now() / 1000);
  if (!timestamp || Math.abs(now - timestamp) > TOLERANCE_SECONDS) {
    return false; // stale / replayed
  }
  const expected = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');

  if (!parts.v1 || parts.v1.length !== expected.length) {
    return false;
  }
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

// In the handler, prefer the V2 header:
//   const ok = verifySignatureV2({
//     rawBody: req.rawBody,
//     signatureHeader: req.headers['x-qualifi-signature-v2'],
//   });

import time

TOLERANCE_SECONDS = 300  # 5 minutes

def verify_signature_v2(raw_body: bytes, signature_header: str) -> bool:
    parts = dict(kv.split("=", 1) for kv in signature_header.split(","))
    timestamp = int(parts.get("t", 0))
    now = int(time.time())
    if not timestamp or abs(now - timestamp) > TOLERANCE_SECONDS:
        return False  # stale / replayed
    signed = f"{timestamp}.".encode() + raw_body
    expected = hmac.new(WEBHOOK_SECRET.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))

# In the handler, prefer the V2 header:
#   ok = verify_signature_v2(
#       request.get_data(),
#       request.headers.get("X-Qualifi-Signature-V2"),
#   )

The X-Qualifi-Signature header shown in the endpoint examples above is deprecated but still sent for backward compatibility. New integrations should verify X-Qualifi-Signature-V2.

Handling Events

Interview Completed

When a candidate completes an interview, the request includes X-Qualifi-Event: candidate_interview.completed and a flat JSON body:

{
  "candidateInterviewId": "uuid",
  "candidateId": "uuid",
  "interviewId": "uuid",
  "completedAt": "2024-01-01T00:00:00.000Z"
}

Action: Fetch interview results and process them:

async function handleInterviewCompleted(payload) {
  const results = await fetch(
    `https://api.prod.qualifi.hr/qsi/gather/candidate-interviews/${payload.candidateInterviewId}/results`,
    {
      headers: {
        'x-api-key': apiKey
      }
    }
  );
  
  const interviewResults = await results.json();
  // Process results: save to database, send notifications, etc.
}

Audio Generated

When question audio generation completes (X-Qualifi-Event: question.audio_generated):

{
  "aiAudioVersionId": "uuid",
  "batchId": "uuid",
  "narratorId": "uuid",
  "audioUrl": "https://...",
  "text": "Question text",
  "createdAt": "2024-01-01T00:00:00.000Z"
}

Action: Update your system with the audio URL.

Status Changed

When candidate interview status changes (X-Qualifi-Event: candidate_interview.status_changed):

{
  "candidateInterviewId": "uuid",
  "candidateId": "uuid",
  "interviewId": "uuid",
  "status": "new_response",
  "previousStatus": null,
  "updatedAt": "2024-01-01T00:00:00.000Z"
}

Action: Update your system’s status tracking. Use status for the new value; previousStatus may be null if the prior status was not captured.

When status changes to new_response, you may receive both candidate_interview.status_changed and candidate_interview.completed webhooks.

Candidate Interview Lifecycle & Workflow Events

Switch on X-Qualifi-Event to handle the remaining events. Each payload schema and a sample delivery are documented in the Webhooks API reference.

Candidate interview lifecycle: candidate_interview.invited, candidate_interview.partially_completed, candidate_interview.expired — track an interview from invite through completion or expiry. invited fires on the actual invite send (not record creation), and workflow-step invites use workflow.step.invited instead, so the two never double-fire.
Workflow lifecycle: workflow.enrollment.created, workflow.enrollment.completed, workflow.enrollment.failed and the per-step workflow.step.invited, workflow.step.completed, workflow.step.failed, workflow.step.waiting_for_evaluation — follow a candidate through a multi-step job workflow. Use enrollmentId to correlate step events with their enrollment.

Best Practices

Verify Signatures: Always verify webhook signatures to ensure authenticity
Idempotency: Handle duplicate webhook deliveries gracefully using event IDs or timestamps
Quick Response: Respond to webhooks quickly (within 5 seconds) to avoid retries
Error Handling: Return appropriate HTTP status codes (200 for success, 4xx/5xx for errors)
Logging: Log all webhook events for debugging and auditing
Async Processing: Process webhook data asynchronously if operations take time

Retry Logic

The Gather API retries failed webhook deliveries:

First attempt: Immediate
Second attempt: After 1 minute
Third attempt: After 5 minutes

If all retry attempts fail, the webhook delivery is marked as failed. Ensure your endpoint is available and handles errors gracefully.

Testing Webhooks

Use a tool like ngrok to test webhooks locally:

# Start your local server
npm start

# In another terminal, expose it via ngrok
ngrok http 3000

# Use the ngrok URL as the webhook URL in your webhook configuration

Webhooks API

Complete webhook API reference

Error Handling

Learn about error handling best practices

Best Practices

Review API best practices

Get Started

API Reference

Guides

Code Examples

Resources

Overview

Setting Up Webhooks

Configuration Requirements

Webhook Endpoint Setup

Basic Endpoint Structure

Verifying the Timestamped Signature (recommended)

Handling Events

Interview Completed

Audio Generated

Status Changed

Candidate Interview Lifecycle & Workflow Events

Best Practices

Retry Logic

Testing Webhooks

Webhooks API

Error Handling

Best Practices

​Overview

​Setting Up Webhooks

​Configuration Requirements

​Webhook Endpoint Setup

​Basic Endpoint Structure

​Verifying the Timestamped Signature (recommended)

​Handling Events

​Interview Completed

​Audio Generated

​Status Changed

​Candidate Interview Lifecycle & Workflow Events

​Best Practices

​Retry Logic

​Testing Webhooks

​Related Resources

Webhooks API

Error Handling

Best Practices

Overview

Setting Up Webhooks

Configuration Requirements

Webhook Endpoint Setup

Basic Endpoint Structure

Verifying the Timestamped Signature (recommended)

Handling Events

Interview Completed

Audio Generated

Status Changed

Candidate Interview Lifecycle & Workflow Events

Best Practices

Retry Logic

Testing Webhooks

Related Resources