# Callback Configuration

## What is a callback?

A callback (also called a webhook) is how JondaX delivers your processed results automatically. Instead of you checking repeatedly whether your file is ready, JondaX sends the data directly to a URL you provide — like getting a delivery notification instead of going to the post office.

If you prefer not to set up a callback, you can skip this step and download your results manually from the **Transformed Files** page in the portal.

## Setup

Before uploading files, configure your callback endpoint on the **Integration** page in the JondaX client portal.

![Callback configuration on Integration page](/assets/callback-config-form.7fb46fc5e5a0ea4c4d0432183731e3a445ef686af3ee31b15a3b0ff78a4f1b65.a1161040.png)

## Your system's URL and keys

| Setting | Required | Description |
|  --- | --- | --- |
| Endpoint URL | Yes | The URL JondaX will POST results to |
| Authentication Header | No | Header name your endpoint expects for auth |
| Authentication Key | No | Header value (shown masked in the portal after saving) |


## Output settings

| Setting | Required | Description |
|  --- | --- | --- |
| Output Language | Yes | The language for biomarker names, categories, and comments in your output. Default: **English (EN)**. See [supported languages](#output-language) below. |
| Payload Type | Yes | `File` or `Inline` — Inline is only available for **JSON** and **FHIR JSON**. All other formats (HL7, FHIR XML, CSV, Parquet) are File only. Default: **Inline** |
| Output Format | Yes | `JSON`, `FHIR JSON`, `HL7`, `FHIR XML`, `CSV`, `Parquet`. Default: **JSON**. |
| Original results in output | No | When enabled, includes raw source data alongside transformed results in the callback payload. Disabled by default. |


## Output language

JondaX can translate the human-readable parts of your output — biomarker names, categories, specimen types, and comments — into your preferred language. Numeric values, units, LOINC codes, and scores are never translated (they are universal).

### Supported languages

| Code | Language |
|  --- | --- |
| `EN` | English (default — no translation applied) |
| `ES` | Spanish |
| `DE` | German |
| `ZH` | Chinese |


### How it works

1. You select your output language on the **Integration** page under Output Settings
2. When your file finishes processing and is approved, JondaX translates the relevant fields automatically
3. The translated output is delivered to your callback URL (or available for download on the Transformed Files page)


### What gets translated

| Translated | Not translated |
|  --- | --- |
| Biomarker names | LOINC codes |
| Category / sub-category labels | Numeric values and ranges |
| Specimen types | Units of measurement |
| Comments | Confidence scores |
| Diagnosis descriptions | Dates and timestamps |


### Good to know

- Translation happens after review approval — it adds 1–5 seconds before delivery (runs in the background, no delay visible to you)
- If you change your output language, it only applies to new files processed after the change
- If you download a file before translation completes, you'll receive the English version with a note that translation is in progress — just download again shortly after
- The source language of the lab report does not need to match the output language — JondaX handles any input language


## Retry behavior

If your callback endpoint is unreachable or returns a non-2xx status, JondaX retries delivery up to **3 times**:

| Attempt | Timing |
|  --- | --- |
| 1st retry | Immediately after failure |
| 2nd retry | 30 minutes later |
| 3rd retry | 6 hours later |


If all retries fail, the result is stored for **30 days** and can be retrieved by contacting support.

## Checking delivery status

Use the status polling endpoint to inspect whether your callback was delivered:

```
GET https://app.jondax.eu/api/v1/status/:uploadId
Authorization: Bearer <JONDAX_API_KEY>
```

The `callbackDelivery.status` field reports one of: `pending`, `delivered`, `retrying`, or `exhausted`. See the [Status Polling](#status-polling) section for full details.

## Verifying callback authenticity

JondaX sends the authentication header name and value you configured on the Integration page with every callback. Verify this header matches your expected value to confirm the request is genuine.

> IP allowlisting will be available in a future release.