# Processing callback
Source: https://docs.file.ai/docs-api/api-processing-callback

> Real-time updates for your file processing pipeline through secure webhook callbacks.

## On this page

*   [Overview](#overview)
*   [🚀 Integration Guide](#-integration-guide)
    *   [1\. Set up your webhook endpoint](#1-set-up-your-webhook-endpoint)
    *   [2\. Configure webhook URL](#2-configure-webhook-url)
    *   [3\. Handle events in your application](#3-handle-events-in-your-application)
    *   [Core Fields](#core-fields)
*   [🔄 Event Types](#-event-types)
    *   [1\. File Uploaded](#1-file-uploaded)
    *   [2\. Processing Started](#2-processing-started)
    *   [3\. Fraud Detection](#3-fraud-detection)
    *   [4\. First Page Analysis](#4-first-page-analysis)
    *   [5\. OCR Processing](#5-ocr-processing)
    *   [6\. OCR Evaluation](#6-ocr-evaluation)
    *   [7\. Split & Classify](#7-split-%26-classify)
    *   [8\. Processing Finished](#8-processing-finished)

Key Functions

# Processing callback

Copy pageCopy page

Real-time updates for your file processing pipeline through secure webhook callbacks.

Copy pageCopy page

## 

[​

](#overview)

**Overview**

Our file processing system sends webhook events to notify your application about the status of uploaded files as they progress through our processing pipeline. Each event contains detailed information about the current processing step and file status. **📋 Quick Facts**

*   **Method**: `POST`
*   **Content-Type**: `application/json`
*   **Retries**: Up to 5 attempts with exponential backoff
*   **Timeout**: 30 seconds

* * *

## 

[​

](#-integration-guide)

**🚀 Integration Guide**

### 

[​

](#1-set-up-your-webhook-endpoint)

**1\. Set up your webhook endpoint**

Create an HTTP endpoint that accepts POST requests and returns a `200` status code to acknowledge receipt of the webhook.

### 

[​

](#2-configure-webhook-url)

**2\. Configure webhook URL**

Set your webhook URL in the dashboard or contact support to configure your callback endpoint.

### 

[​

](#3-handle-events-in-your-application)

**3\. Handle events in your application**

Your endpoint will receive JSON payloads for each processing step. Parse the `status`, `step`, `uploadId`, and `fileIds` fields to track file processing progress.

```

---

## 📊 Processing Workflow

Your files progress through our automated processing pipeline:
```

📁 File Upload  
↓ ⚡ Processing Started ↓ 🛡️ Fraud Detection ↓ 📄 First Page Analysis ↓ 🔍 OCR Processing ↓ ✅ OCR Evaluation ↓ 📑 Split & Classify ↓ 🎉 Processing Finished

````

---

## 📋 Event Reference

### Base Event Structure

All webhook events share this common structure:

```json
{
  "status": "completed",
  "step": "processing_started",
  "uploadId": "e9818d17-e5be-4d57-bdc8-5a40b4f6f4e1",
  "timestamp": "2025-06-11T10:30:00Z",
  "fileIds": "b765bd00-181e-4737-b4d9-004dadd6bd45"
}
````

#### 

[​

](#core-fields)

**Core Fields**

**Field**

**Type**

**Description**

`status`

`string`

Current status: `waiting`, `completed`, `failed`

`step`

`string`

Processing step identifier

`uploadId`

`string`

Unique identifier for the upload session

`timestamp`

`string`

ISO 8601 timestamp when event occurred

`fileIds`

`string`

Available in final steps - processed file IDs

* * *

## 

[​

](#-event-types)

**🔄 Event Types**

### 

[​

](#1-file-uploaded)

**1\. File Uploaded**

**Step**: `file_uploaded`  
**When**: File successfully uploaded to our system JSON

```
{
  "status": "completed",
  "step": "file_uploaded",
  "uploadId": "e9818d17-e5be-4d57-bdc8-5a40b4f6f4e1",
  "timestamp": "2025-06-11T10:30:00Z"
}
```

**Next Step**: `processing_started`

* * *

### 

[​

](#2-processing-started)

**2\. Processing Started**

**Step**: `processing_started`  
**When**: File enters processing queue JSON

```
{
  "status": "waiting",
  "step": "processing_started", 
  "uploadId": "e9818d17-e5be-4d57-bdc8-5a40b4f6f4e1",
  "timestamp": "2025-06-11T10:30:15Z"
}
```

JSON

```
{
  "status": "completed",
  "step": "processing_started",
  "uploadId": "e9818d17-e5be-4d57-bdc8-5a40b4f6f4e1", 
  "timestamp": "2025-06-11T10:30:30Z"
}
```

**Status Flow**: `waiting` → `completed`  
**Next Step**: `fraud_detection`

* * *

### 

[​

](#3-fraud-detection)

**3\. Fraud Detection**

**Step**: `fraud_detection`  
**When**: Security and fraud checks completed JSON

```
{
  "status": "completed",
  "step": "fraud_detection",
  "uploadId": "e9818d17-e5be-4d57-bdc8-5a40b4f6f4e1",
  "timestamp": "2025-06-11T10:31:00Z"
}
```

**Next Step**: `first_page_analysis`

* * *

### 

[​

](#4-first-page-analysis)

**4\. First Page Analysis**

**Step**: `first_page_analysis`  
**When**: Initial document analysis completed JSON

```
{
  "status": "completed",
  "step": "first_page_analysis",
  "uploadId": "e9818d17-e5be-4d57-bdc8-5a40b4f6f4e1",
  "timestamp": "2025-06-11T10:31:30Z"
}
```

**Next Step**: `beethoven_ocr`

* * *

### 

[​

](#5-ocr-processing)

**5\. OCR Processing**

**Step**: `beethoven_ocr`  
**When**: Optical Character Recognition completed JSON

```
{
  "status": "completed", 
  "step": "beethoven_ocr",
  "uploadId": "e9818d17-e5be-4d57-bdc8-5a40b4f6f4e1",
  "timestamp": "2025-06-11T10:32:15Z"
}
```

**Next Step**: `ocr_evaluation`

* * *

### 

[​

](#6-ocr-evaluation)

**6\. OCR Evaluation**

**Step**: `ocr_evaluation`  
**When**: OCR quality assessment completed JSON

```
{
  "status": "completed",
  "step": "ocr_evaluation", 
  "uploadId": "e9818d17-e5be-4d57-bdc8-5a40b4f6f4e1",
  "timestamp": "2025-06-11T10:32:45Z"
}
```

**Next Step**: `split_classify`

* * *

### 

[​

](#7-split-&-classify)

**7\. Split & Classify**

**Step**: `split_classify`  
**When**: Document splitting and classification completed JSON

```
{
  "status": "completed",
  "step": "split_classify",
  "uploadId": "e9818d17-e5be-4d57-bdc8-5a40b4f6f4e1",
  "fileIds": ["b765bd00-181e-4737-b4d9-004dadd6bd45"],
  "timestamp": "2025-06-11T10:33:15Z"
}
```

**📌 Important**: First event where `fileIds` becomes available  
**Next Step**: `processing_finished`

* * *

### 

[​

](#8-processing-finished)

**8\. Processing Finished**

**Step**: `processing_finished`  
**When**: All processing completed successfully JSON

```
{
  "status": "completed",
  "step": "processing_finished",
  "uploadId": "e9818d17-e5be-4d57-bdc8-5a40b4f6f4e1",
  "fileIds": ["b765bd00-181e-4737-b4d9-004dadd6bd45"],
  "timestamp": "2025-06-11T10:33:30Z"
}
```

**🎉 Final Step**: Your files are ready for download/use

[

Schema Locking

](/docs-api/api-schema-locking)[

Incremental Loading (CDC)

](/docs-api/api-incremental-data-loading)

[linkedin](https://www.linkedin.com/company/file-ai)[x](https://x.com/fileAI_)[youtube](https://www.youtube.com/@file_AI)

[Powered byThis documentation is built and hosted on Mintlify, a developer documentation platform](https://www.mintlify.com?utm_campaign=poweredBy&utm_medium=referral&utm_source=undefined)