Zapier and n8n

Send documents from other apps into a workflow, and push results back out when processing finishes - without writing code. Zapier and n8n are available on every plan.

The Foxello app for Zapier is available on request - contact us and we will send you access.

How it works

1. Add an integration. Open Integrations in the sidebar, select Add integration, choose Zapier or n8n, and give it a name. You get a connection key - copy it, it is shown only once.
2. Connect your tool. In Zapier or n8n, connect your account and paste the connection key.
3. Create a workflow for it. In Add workflow, choose Zapier or n8n as the import method (to receive documents from it), the export destination (to send results to it), or both.
4. Pick the integration. Open the workflow's Edit dialog and select your integration on the Import tab, the Export tab, or both.

A workflow's import method and export destination are chosen when it is created and cannot be changed later - to use a different method, create a new workflow. You can still switch the workflow to another integration of the same type.

A connection key can only reach the workflows that selected its integration. One integration can serve many workflows, and you can add separate integrations for different Zapier or n8n accounts.

Only Owners and Admins can add, regenerate, or remove integrations. Everyone in the account can see them.

What your automations can do

Triggers only fire for workflows whose Export destination is that integration.

Export status of files

For workflows that export to Zapier or n8n, a file is marked exported once every automation listening for Document completed has received it. If one of them still cannot be reached after all retries, or is paused after repeated failures, the file's export is marked as failed - open the integration on the Integrations page and check Deliveries.

If no automation is listening when the results become final, nothing is delivered and the file stays approved (or processed), the same as a workflow with manual web export.

Managing integrations

The Integrations page lists every integration with:

• the start of its connection key, so you can tell keys apart;
• how many workflows use it;
• how many automations are listening for events, and whether any are paused;
• when it was last used.

Select a row to see which workflows send documents to it or receive results from it, and every automation subscribed to its events. From there you can:

• Deliveries - see the last deliveries of an automation: when they were sent, whether they succeeded, and the receiving side's response code.
• Resume - an automation is paused after three events in a row could not be delivered. Fix the problem on the receiving side, then resume it.
• Disconnect - stop sending events to an automation. Turning off the Zap or deactivating the n8n workflow does the same automatically.

Use Regenerate key if a key was exposed: the old key stops working immediately, so update it in Zapier or n8n. Remove revokes the key and disconnects every automation that uses the integration.

Connecting with HTTP steps

If Foxello does not appear in your tool's app list yet, use its HTTP request step (for example Webhooks by Zapier or the n8n HTTP Request node) with these endpoints. Send the connection key as Authorization: Bearer <connection key>.

Base URL: https://api.foxello.com/api/v1

The Integration API Reference lists every endpoint with its parameters, responses, and error codes.

Connection

• GET /me - test the connection.

Workflows

• GET /workflows?purpose=import - workflows that accept documents from this integration. Use purpose=export for workflows that send results to it.
• GET /workflows/{workflowId}/fields - the fields the workflow extracts, per document type, in the same docType / attribute structure as a document's fields. Use it to set up field mapping before any document has been processed.

Sending documents

• POST /workflows/{workflowId}/documents - upload a file as the multipart/form-data field file (up to 5 MB), or send JSON { "url": "https://..." } to fetch a file from a link (up to 100 MB).
• POST /workflows/{workflowId}/documents/uploads - for larger files:
  1. Send { "fileName", "fileSize" }.
  2. Upload the bytes with PUT to the returned uploadUrl.
  3. Call POST .../uploads/{uploadId}/complete.

Reading results

• GET /documents?status=completed&limit=10 - newest documents of connected workflows. status can be completed, needs_review, failed, or processing.
• GET /documents/{documentId} - one document with its extracted fields.
• GET /documents/{documentId}/original - a short-lived link to download the original file.
• GET /documents/{documentId}/results?format=csv - the extracted results as a file: json, csv, or xlsx (Excel, Growth and Scale plans). Returns 409 until the document has finished processing and, if required, been approved.

Event subscriptions

• POST /webhooks - subscribe a URL to an event: { "targetUrl", "event", "workflowId" }. workflowId is optional.
• GET /webhooks/{subscriptionId} - read a subscription and its status.
• DELETE /webhooks/{subscriptionId} - unsubscribe.

Rate limit

Each connection key can make up to 300 requests per minute. Above that, requests are answered with 429 Too Many Requests and a Retry-After header saying how many seconds to wait. Zapier and n8n retry automatically. Other integrations on the same account have their own limit.

Avoiding duplicate documents

Zapier and n8n retry a step that timed out, and you can replay a past run. To make sure a retry does not process the same document twice, send an Idempotency-Key header with the upload - any unique value per document, such as the run or record ID, up to 255 characters without spaces.

• Sending the same key again within 24 hours returns the document created by the first request instead of creating a new one.
• If the first request is still being received, the retry gets 409 - try again a minute later.
• If the first request failed, the key is freed and a retry with it is processed normally.
• A key belongs to one workflow: reusing it for another workflow returns 400.

Events

Events are document.completed, document.needs_review, document.approved, and document.failed. Target URLs must be public https addresses on the standard port (443) - a self-hosted n8n on another port needs a reverse proxy in front of it.

Event payload

Each event is a JSON POST with the document and the event details:

{
  "id": "6a1f2763e4b82c58360f9700",
  "name": "invoice-1042.pdf",
  "status": "approved",
  "workflowId": "65f15b4ab5a16c0012b7a901",
  "workflowName": "Invoice Processing",
  "pageCount": 2,
  "confidenceScore": 0.94,
  "createdAt": "2026-10-12T09:58:02.000Z",
  "updatedAt": "2026-10-12T10:01:40.000Z",
  "fields": { "...": "extracted fields" },
  "event": "document.completed",
  "eventId": "6a1f27a0e4b82c58360f9711",
  "occurredAt": "2026-10-12T10:01:41.000Z"
}

fields is included once processing has finished.

Verifying events

When you subscribe, the response includes a signing secret. Every delivery carries:

• X-Foxello-Event - the event type
• X-Foxello-Event-Id - the same value on every retry of one event, so you can drop duplicates
• X-Foxello-Timestamp - Unix time in seconds
• X-Foxello-Signature - v1= followed by the HMAC-SHA256 of <timestamp>.<raw body> using the secret

Reject requests whose signature does not match or whose timestamp is more than a few minutes old.

Delivery rules

• Answer with any 2xx status to confirm delivery.
• Other answers and timeouts are retried automatically: Document completed about 5 and 10 minutes later, the other events about 1, 2, and 4 minutes later. A receiver that already answered 2xx is not sent the same event again on a retry.
• Document completed is sent within about a minute of the results becoming final; the other events are sent right away.
• Answer 410 Gone to unsubscribe for good.
• Delivery history is kept for 30 days.

Webhook export

To send results to your own endpoint instead of Zapier or n8n, set the workflow export destination to API and enter an https URL. Each processed document is sent as a JSON POST, signed with X-Signature when you generate a signing secret on the Export tab. The URL must be a public address.

See API Integration for the workflow API token, upload, status, and download endpoints.

Tips

• Test with a single file before connecting high-volume automation.
• Use one integration per Zapier or n8n account so you can regenerate or remove one without touching the others.
• Keep connection keys and signing secrets in your tool's credential storage, never in plain text steps.