n8n-nodes-fillo

n8n community nodes for Fillo. Start a workflow the moment a form response lands, and read forms and responses from your workspace.

The package ships two nodes and one credential:

| Item | Name in n8n | What it does | | --- | --- | --- | | Trigger node | Fillo Trigger | Registers a Fillo webhook for one form and starts the workflow on response.created / response.updated | | Action node | Fillo | Reads forms (Get Many) and responses (Get Many) | | Credential | Fillo API | Your workspace API token, plus the Fillo URL for self-hosted installs |

Install

Self-hosted n8n: Settings → Community Nodes → Install, then enter the package name:

n8n-nodes-fillo

n8n Cloud: verified community nodes can be installed from the in-app catalogue. This package is not verified yet, so on Cloud use the signed webhook path with n8n's built-in Webhook node until verification lands.

Requires Node 22 or newer (the same floor as current n8n).

Connect your workspace

1. In Fillo, open Settings → Connections → n8n and create a token. It starts with fcli_ and carries your workspace's form access — treat it like a password.
2. In n8n, create a Fillo API credential and paste the token.
3. Leave Fillo URL at https://fillo.so unless you run Fillo on your own domain.
4. Hit Test. n8n calls GET /api/v1/connect/auth and shows the workspace the token belongs to.

Deleting the token in Fillo also removes every webhook subscription it created, so revoking access cannot leave hooks firing behind your back.

Fillo Trigger

1. Add Fillo Trigger to a workflow and pick the credential.
2. Choose a Form. The dropdown lists the published forms this token can reach.
3. Choose the Events you care about — Response Created, Response Updated, or both (the default).
4. Activate the workflow. n8n registers its webhook URL with Fillo (POST /api/v1/connect/hooks); deactivating it unregisters again (DELETE /api/v1/connect/hooks).

Each delivery arrives as one item whose json is the raw Fillo payload, so you can map answers, formatted, fields[], and files[] visually.

Payload

{
  "event": "response.created",
  "id": "wA3kR9tL0qBn",
  "response_id": "wA3kR9tL0qBn",
  "occurrence_id": "occ_7Qm2",
  "submitted_at": "2026-07-04T09:41:23.512Z",
  "form_id": "Jf2mX8pQ4sDv",
  "form_name": "Conversion failed",
  "form_slug": "conversion-failed",
  "form_url": "https://fillo.so/f/conversion-failed",
  "source": "app.example.com/convert",
  "duration_ms": 8200,
  "respondent": { "id": "user_1042", "email": "[email protected]", "name": "Ada", "verified": true },
  "answers": { "reason": "crash", "details": "Export hung at 90%" },
  "formatted": { "reason": "It crashed", "details": "Export hung at 90%" },
  "fields": [
    { "id": "reason", "label": "What went wrong?", "kind": "select", "value": "crash", "formatted": "It crashed" }
  ],
  "files": [],
  "meta": { "source": "app.example.com/convert", "duration_ms": 8200 },
  "form": { "id": "Jf2mX8pQ4sDv", "slug": "conversion-failed", "name": "Conversion failed" },
  "response": { "id": "wA3kR9tL0qBn", "answers": {}, "formatted": {}, "fields": [], "createdAt": "2026-07-04T09:41:23.512Z" }
}

answers is keyed by field id with raw values; formatted holds display strings (option labels, not ids). respondent is null when no identity was recorded; its verified flag says whether the project HMAC check passed. The top level and the nested form / response views overlap but do not have identical keys, so pick fields explicitly. The full reference lives at fillo.so/docs/webhooks.

Delivery semantics

• Delivery is at-least-once. The same event can arrive twice if an acknowledgment is lost.
• Failures retry with backoff — roughly 1 minute, 5 minutes, 30 minutes, 2 hours, then 6 hours — up to 6 attempts, with a 10-second timeout per attempt.
• Every request carries X-Fillo-Delivery-Id, stable across retries of one delivery. If your workflow writes to a system that cannot absorb a duplicate, dedupe on it — or, inside n8n where headers are not part of the item, on occurrence_id (unique per event, stable across retries) together with response_id.
• Do not dedupe on response_id alone: one response emits response.created and can emit response.updated later.
• Files appear in files[] as references. Their url needs the same Fillo token, so fetch them with an HTTP Request node using the Fillo API credential rather than passing the link to a service that cannot authenticate.

Trust model

The Fillo Trigger relies on the unguessability of n8n's webhook URL — the same stance as Fillo's Zapier REST hooks. Fillo signs deliveries with X-Fillo-Signature, but the signing secret is not exposed on the connector surface, so this node does not verify it. If you need signature verification, configure a per-form webhook under Form settings → Webhooks and receive it with n8n's built-in Webhook node instead; that path hands you the secret and the X-Fillo-Signature header to check against the raw body.

Keep the workflow's webhook URL private, and rotate it (deactivate, then reactivate the workflow) if it leaks.

Fillo action node

| Resource | Operation | Request | | --- | --- | --- | | Form | Get Many | GET /api/v1/connect/forms — published forms this token can reach | | Response | Get Many | GET /api/v1/connect/responses?formId=…&limit=… — most recent first, 1–50 |

A form with no responses yet answers with one sample response built from its schema, so you can map fields before the first real submission arrives. Check response_id if you need to tell a sample from a real answer.

Local development

pnpm --filter n8n-nodes-fillo build   # n8n-node build → dist/
pnpm --filter n8n-nodes-fillo lint    # n8n-node lint (community-node rules)
pnpm --filter n8n-nodes-fillo test    # builds, then runs the smoke tests against dist/
pnpm --filter n8n-nodes-fillo dev     # n8n-node dev: local n8n with this package linked

The package uses n8n's official @n8n/node-cli for build, lint, and dev — n8n Cloud verification requires it. It has zero runtime dependencies by design; everything in devDependencies stays out of the published tarball, which contains only dist/.

Publishing runs through the repository's Changesets flow, not n8n-node release.

Server contract

Both nodes speak to Fillo's provider-neutral connector surface, authenticated with Authorization: Bearer <token>:

| Route | Purpose | | --- | --- | | GET /api/v1/connect/auth | Credential test — returns the user and workspace | | GET /api/v1/connect/forms | Form dropdown | | GET /api/v1/connect/responses | Response reads and schema samples | | POST /api/v1/connect/hooks | Subscribe (idempotent per form + target URL) | | DELETE /api/v1/connect/hooks | Unsubscribe (idempotent) |

Licence

MIT