Kovi Webhooks: Real-Time Interview Scorecard Delivery

​

How Webhooks Work

1. Interview concludes. The candidate submits their final response and Kovi finalises the evaluation.
2. Kovi prepares the scorecard JSON. Scores, proctoring flags, strengths, weaknesses, and the transcript URL are assembled into a structured payload.
3. Kovi sends an HTTP POST to your configured endpoint. The request is dispatched within seconds of interview completion.
4. Your server receives and processes the payload. Parse the JSON body and extract the fields relevant to your workflow.
5. Update your ATS or database. Write the scorecard data to your candidate record, trigger downstream notifications, or automate next-stage scheduling.

​

Setting Up Your Webhook URL

​

Delivery Guarantees

• Immediate dispatch. The webhook is triggered the instant an interview is marked complete—there is no scheduled batch window or delay.
• Automatic retries. If your endpoint returns a non-2xx HTTP status code, Kovi retries the delivery up to 3 times using exponential backoff (approximately 30 s, 2 min, and 8 min between attempts).
• Respond quickly. Your endpoint should return a 2xx response within 10 seconds. If processing takes longer, acknowledge the request immediately and handle the payload asynchronously.

​

Security

from flask import Flask, request, abort

app = Flask(__name__)

KOVI_SECRET = "your_shared_secret_token_here"

@app.route("/kovi/webhook", methods=["POST"])
def kovi_webhook():
    # Retrieve the secret header sent by Kovi
    received_secret = request.headers.get("X-Kovi-Secret")

    # Reject the request if the header is missing or does not match
    if received_secret != KOVI_SECRET:
        abort(403)

    payload = request.get_json()

    # Process the scorecard payload
    candidate_id = payload.get("candidate_id")
    final_score = payload.get("final_score")
    passed = payload.get("passed_threshold")

    print(f"Scorecard received — Candidate: {candidate_id}, Score: {final_score}, Passed: {passed}")

    # Return 200 to acknowledge receipt
    return "", 200