> ## Documentation Index
> Fetch the complete documentation index at: https://docs.techeval.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Kovi ATS Integration: Webhook Scorecard Delivery Setup

> Connect Kovi to your Applicant Tracking System by configuring a webhook endpoint that receives structured scorecard JSON on interview completion.

Kovi delivers interview scorecards to your ATS via a webhook POST request the moment an interview ends. You configure the endpoint URL in your Techeval dashboard, and Kovi handles the rest.

## How the Integration Works

1. Configure your webhook URL in the Techeval dashboard.
2. Kovi sends a POST request with the scorecard JSON when an interview completes.
3. Your ATS receives the payload and updates the candidate record.

No polling, no manual exports — the scorecard arrives in your system automatically, within seconds of the interview ending.

## Setting Up Your Webhook Endpoint

<Steps>
  <Step title="Open Integrations Settings">
    Log in to your Techeval dashboard and go to **Settings → Integrations**.
  </Step>

  <Step title="Enter Your Webhook URL">
    Paste your ATS webhook URL into the **Webhook Endpoint** field. The URL must use **HTTPS** — plain HTTP endpoints are not accepted.
  </Step>

  <Step title="Add a Secret Token (Optional)">
    Optionally enter a secret token. Kovi will include this token in the request headers so your endpoint can verify that the payload originated from Kovi.
  </Step>

  <Step title="Save and Test">
    Click **Save**, then use the **Send Test Delivery** button to fire a sample scorecard payload to your endpoint. Confirm your ATS received it before going live.
  </Step>
</Steps>

<Warning>
  Your webhook endpoint must return a **2xx response within 10 seconds**, otherwise Kovi will retry delivery. Make sure any heavy processing (e.g., database writes) happens asynchronously after you respond.
</Warning>

## Handling the Payload in Python

The following example shows a minimal FastAPI receiver that extracts the key fields from the scorecard payload:

```python webhook_receiver.py theme={null}
from fastapi import FastAPI, Request

app = FastAPI()

@app.post("/kovi-webhook")
async def receive_scorecard(request: Request):
    payload = await request.json()
    candidate_id = payload["candidate_id"]
    score = payload["final_score"]
    passed = payload["passed_threshold"]
    # Update your ATS here
    print(f"Candidate {candidate_id}: {score} | Passed: {passed}")
    return {"status": "received"}
```

Return `{"status": "received"}` (or any 2xx JSON response) immediately, then handle downstream ATS updates in a background task or message queue to stay within the 10-second response window.

<Note>
  All webhook requests are sent over HTTPS. Keep your webhook endpoint publicly accessible so Kovi can reach it — private network or localhost URLs will not work.
</Note>

## Custom Integrations

Kovi's webhook delivers a standard JSON scorecard that you can map to any ATS field schema. For native, pre-built integrations with platforms such as **Greenhouse**, **Lever**, **Workday**, or other enterprise ATS tools, contact the Techeval team at [contact@techeval.ai](mailto:contact@techeval.ai). Custom integrations are available for teams with specific workflow requirements.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.