Processing callbacks

A processing callback is a POST that fileAI sends to your callback URL as an upload moves through processing. It tells you which step finished, whether it succeeded, and, once the upload has been split into documents, the fileId of each document, so you can fetch values without polling. This page is the payload reference. To choose between callbacks and polling, and for extract, split, classify and agent job callbacks, see Async jobs. For signed events about files, uploads, folders and File Agents, set up webhooks.

Upload callbacks are sent once and not retried. If your endpoint is down or returns an error, that event is lost. Keep polling GET /v1/uploads/{uploadId} as a fallback. See Async jobs.

How it works

Where the callback goes

You set callbackURL when you request the upload, or rely on your API key’s default callback URL. Multipart uploads do not fall back to the key’s default. The full rules are under Upload options. Files added in the fileAI app or by email use your organization’s file-processing callback URL, if one is set. Use an HTTPS URL that accepts POST with a JSON body. Any #fragment on the URL is dropped before sending.

What gets sent

Each event is a single POST with Content-Type: application/json. There are no other custom headers: no signature, no timestamp, no event id. fileAI logs your response status but does not act on it, and sets no client timeout of its own. A typical successful upload sends events for these steps, in roughly this order: processing_started usually arrives twice: first with waiting, then with completed. Not every upload passes through every step, and the order is not guaranteed: key your logic on step and status, not on position. fileIds first appears on split_classify, and again on processing_finished. An upload that fails sends processing_failed with status error and an errorReason.

Reprocessing a document (for example, replacing its file) can send another round of events for the same uploadId, including beethoven_ocr or ai_form_filling with status processing and a further processing_finished. Make your handler safe to run more than once.

Handle callbacks safely

Upload callbacks are not signed, so anyone who learns your callback URL can send a request that looks like one. Treat a callback as a signal to check, not as proof:

Put a token in the callback URL

Add an unguessable value to the query string of each upload’s callbackURL, for example https://example.com/fileai/callback?token=8f3c…, and reject requests without it. fileAI keeps the query string and drops only a #fragment. This stops requests from anyone who doesn’t know the URL; it is not a signature.

Confirm the state with the API

Before anything consequential (paying, approving, releasing a claim), fetch the upload with your API key: GET /v1/uploads/{uploadId}. Act on the status of each document in files (for example processed), not on the callback body. See Uploads in Async jobs.

Make the handler safe to repeat

The same uploadId can send processing_finished more than once (see reprocessing above). Record which uploadId and fileIds you have already handled and skip repeats.

Keep a polling fallback

Callbacks are not retried. For any upload that hasn’t reached processing_finished in the time you expect, poll GET /v1/uploads/{uploadId}, or pull changes on a schedule with incremental loading.

Example

A successful upload that produced two documents ends with:

{
  "step": "processing_finished",
  "status": "completed",
  "uploadId": "e9818d17-e5be-4d57-bdc8-5a40b4f6f4e1",
  "fileIds": "b765bd00-181e-4737-b4d9-004dadd6bd45,3c1a9f02-77e4-4b1e-9a51-2f0d6c8e4a10"
}

A failed upload sends:

{
  "step": "processing_failed",
  "status": "error",
  "uploadId": "e9818d17-e5be-4d57-bdc8-5a40b4f6f4e1",
  "errorReason": "ocr_failed"
}

A minimal receiver checks the token, acknowledges fast, and hands the upload to a worker. The worker calls GET /v1/uploads/{uploadId} and uses only documents whose status is processed. fileIds is one comma-joined string, not an array, so split it before you record which documents you have handled.

import hmac, os
from flask import Flask, abort, request

app = Flask(__name__)

@app.post("/fileai/callback")
def fileai_callback():
    if not hmac.compare_digest(request.args.get("token", ""), os.environ["CALLBACK_TOKEN"]):
        abort(401)
    event = request.get_json()
    if event["step"] == "processing_finished" and event["status"] == "completed":
        file_ids = event.get("fileIds", "").split(",")  # a string, not an array
        enqueue_confirm_upload(event["uploadId"], file_ids)
    elif event["status"] == "error":
        enqueue_confirm_upload(event["uploadId"], [])
    return "", 200

import crypto from "node:crypto";
import express from "express";

const app = express();
app.use(express.json());

const expected = Buffer.from(process.env.CALLBACK_TOKEN);

app.post("/fileai/callback", (req, res) => {
  const token = Buffer.from(String(req.query.token ?? ""));
  if (token.length !== expected.length || !crypto.timingSafeEqual(token, expected)) {
    return res.sendStatus(401);
  }
  const { step, status, uploadId, fileIds } = req.body;
  if (step === "processing_finished" && status === "completed") {
    enqueueConfirmUpload(uploadId, (fileIds ?? "").split(",")); // a string, not an array
  } else if (status === "error") {
    enqueueConfirmUpload(uploadId, []);
  }
  res.sendStatus(200);
});

Reference

Payload fields

Field	Type	Present	Description
`step`	string	Always	The processing step this event is about. See below.
`status`	string	Always	`waiting`, `processing`, `completed` or `error`.
`uploadId`	string	Always	The `uploadId` returned when you created the upload.
`fileIds`	string	`split_classify` and `processing_finished`	The `fileId`s of the documents produced from the upload, joined with commas into one string. Split it yourself.
`errorReason`	string	Only when there is a reason	Machine-readable failure reason, such as `ocr_failed`, `password_protected` or `corrupted_file`.

There is no timestamp field. Record the time you received the event if you need one; GET /v1/uploads/{uploadId} returns a timestamp per step.

Statuses

`status`	Meaning
`waiting`	The step is queued. Sent for `processing_started`.
`processing`	The step is running. Sent when a document is reprocessed.
`completed`	The step finished successfully.
`error`	The step failed. On `split_classify`, it means the upload needs attention; check `errorReason`.

Steps

`step`	Sent when
`file_uploaded`	The file has landed in storage.
`processing_started`	The upload enters the processing queue (`waiting`), then starts (`completed`).
`fraud_detection`	An internal processing step has finished. This is not fileForensics.
`first_page_analysis`	First-page analysis has finished.
`beethoven_ocr`	OCR has finished.
`ocr_evaluation`	OCR quality checks have finished.
`split_classify`	The upload has been split into documents and classified. First event carrying `fileIds`.
`ai_form_filling`	A reprocessed document’s values are being extracted again.
`processing_finished`	All documents are processed. Carries `fileIds`.
`processing_failed`	Processing stopped with an error. Carries `errorReason` when one is known.

Async jobs

Upload status polling, and callbacks for extract, split, classify and agent jobs.

Uploads

Single, batch and multipart uploads, where you set callbackURL.

Incremental loading

Pull new and changed files on a schedule instead of reacting to events.

API quickstart

Upload a file and read its values end to end.

Get started

Products

Build

Go live

How it works

Where the callback goes

What gets sent

Handle callbacks safely

Example

Reference

Payload fields

Statuses

Steps

Async jobs

Uploads

Incremental loading

API quickstart

​How it works

​Where the callback goes

​What gets sent

​Handle callbacks safely

​Example

​Reference

​Payload fields

​Statuses

​Steps

​Related

Async jobs

Uploads

Incremental loading

API quickstart

How it works

Where the callback goes

What gets sent

Handle callbacks safely

Example

Reference

Payload fields

Statuses

Steps

Related