POST to an HTTPS URL you own when something happens in your fileAI project, such as a file finishing processing or a File Agent checklist passing. You choose the events. fileAI signs every request with a secret that only you and fileAI know, and records each delivery so you can check it in the app.
You set up webhooks in the fileAI app. There is no public API to create or manage them yet.
When to use it
How it works
- A webhook belongs to one project and receives only that project’s events.
- Every active webhook subscribed to an event gets its own copy.
- The body is small: an
eventId, theeventCode, and the IDs of what changed. Use the API to fetch the details. - A delivery succeeds when your endpoint returns any
2xxstatus. Anything else is recorded as failed and is not retried.
Set up a webhook
1
Open Webhooks
In the fileAI app, select Developer in the left sidebar, then open the Webhooks tab.
2
Add the webhook
Click Add Webhook. Enter a Name (3–150 characters) and the Endpoint URL. The URL must use HTTPS and be at most 2,048 characters.
3
Choose events
Select at least one event under Events to send (Automatic), Events to send (File Agent), or both. An event can be in only one of the two sections. A greyed-out event isn’t enabled for your project.
4
Save the signing secret
Click Add webhook. fileAI shows the Signing secret, which starts with
fileai_whsec_. Click Confirm and copy and store it in your secret manager. You can’t view it again. After this, the app shows only a masked value such as fileai_whsec_****Ab3x.Send File Agent events
folder.checklist.validation.completed and the File Agent version of folder.processing.completed come from a File Agent’s checklist. To receive them:
- Subscribe a webhook to the event under Events to send (File Agent).
- Open the File Agent’s checklist, turn on Webhook, and add the events under Events.
Verify the signature
Every request carries these headers:X-FileAI-Timestamp: when fileAI signed the request, in Unix seconds.X-FileAI-Signature: the hex-encoded HMAC-SHA256 of{timestamp}.{raw body}, keyed with your signing secret. Use the whole secret, including thefileai_whsec_prefix.X-FileAI-Signature-Version:v1.
1
Read the raw body
Use the request body exactly as received, before you parse it. JSON that has been parsed and serialized again won’t match.
2
Check the timestamp
Reject requests whose
X-FileAI-Timestamp is far from your clock. We suggest 5 minutes. This stops an old request from being replayed.3
Compute and compare
Compute HMAC-SHA256 over the timestamp, a
., and the raw body, using your signing secret as the key. Hex-encode the result. Compare it to X-FileAI-Signature with a constant-time comparison, and reject the request if they differ.Example
Illustrative: shape from the webhook service.200. already_handled and enqueue stand for your own storage and job queue.
Handle events safely
1
Respond fast
Return a
2xx within 10 seconds and do the real work in a background job. fileAI waits up to 3 seconds to connect and 10 seconds for the whole request. A slower response is recorded as failed.2
Skip duplicates
The same event can reach you more than once, with the same
eventId. Record the eventIds you have handled and skip repeats.3
Expect the same change to fire again
Some events fire again for the same file or folder, each time with a new
eventId. For example, a file that is reprocessed can finish again, and a folder that already completed can complete again after more files are added. Make your processing safe to run twice for the same fileId or folderId.4
Fetch the current state
The body says what changed, not its full state. Before anything consequential, call the API with your key, for example
GET /v1/files/{fileId}/values or GET /v1/directories/{directoryId}/checklist-validation.5
Keep a fallback
Failed deliveries are not retried. If your endpoint was down, catch up with incremental loading or by polling the API.
Check deliveries
In the app, open Developer → Activity log → Webhooks. Each row shows the date and time, endpoint URL, event code and status. Open a row to see the Payload Request fileAI sent and the Response your endpoint returned. In the Webhooks list, Last triggered shows when each webhook last received an event.Rotate the signing secret
There is no option to regenerate a secret yet. To rotate it:- Add a new webhook with the same URL and events, and save its secret.
- Update your endpoint to accept either secret.
- Delete the old webhook, then remove the old secret from your endpoint.
eventId. Your duplicate check drops the second copy.
Reference
Request
Body
The body has no timestamp, workspace ID or project ID. Record the time you received the request if you need one.
Events
Data fields
Example body for each event
Example body for each event
Delivery behavior
Troubleshooting
Related
Processing callbacks
Follow every processing step of one upload at a URL you set per request.
Incremental loading
Catch up on changes you missed by pulling them on a schedule.
Async jobs
Poll uploads and jobs when you need a fallback.
Notifications
Email people when a document meets your conditions.