0.1.1 • Published yesterday

@empirio-ai/n8n-nodes-empirio-ai

Licence

MIT

Version

0.1.1

Deps

Size

137 kB

Vulns

Weekly

Summary Dependency Versions

@empirio-ai/n8n-nodes-empirio-ai

n8n community nodes for empirio.ai — build, publish and analyse online surveys, and start a workflow the moment a respondent submits an answer.

The package contains two nodes:

Node	Type	What it does
empirio.ai	Action	Create, update, publish, duplicate and delete surveys; read responses, aggregates, cross-tabulations, question catalogs, statistics and exports
empirio.ai Trigger	Trigger	Runs the workflow whenever a response is submitted, delivered over a signed webhook

Installation · Credentials · Empirio node · empirio.ai Trigger · Self-hosted and Cloud · Rate limits · Compatibility

Installation

Requirements

An empirio account on the Pro or Enterprise plan. The platform API and webhooks are gated to those plans. The credential test is the one call allowed on every plan, so a credential on a lower plan still validates — the operations then fail with plan_required.
n8n 1.x or later.

Both nodes offer the same two authentication methods through an Authentication selector. Pick whichever suits the deployment — an API key is the fastest to set up, OAuth2 avoids storing a long-lived key.

Empirio API (API key)

Sign in at empirio.ai and open Integrations.
Under REST API, create a key. The key is shown once — copy it right away.
In n8n, create an Empirio API credential and paste the key into API Key.

Empirio OAuth2 API

empirio supports confidential OAuth clients, and every n8n instance registers its own. This is why the flow works even though the redirect URL depends on your n8n host.

In n8n, create an Empirio OAuth2 API credential. n8n shows an OAuth Redirect URL at the top of the credential — copy it. It looks like https://<your-n8n-host>/rest/oauth2-credential/callback.
Sign in at empirio.ai, open Integrations and go to OAuth clients.
Create a client and paste the copied redirect URL into Redirect URIs. empirio shows the Client ID and Client secret once — copy both.
Back in n8n, paste them into Client ID and Client Secret, then click Connect my account and approve the consent screen.

The credential uses the authorization code flow with PKCE (S256) and requests the surveys and responses scopes. Access tokens are refreshed automatically.

The redirect URL must match exactly, including the scheme and any port. If your n8n host name changes, register the new redirect URL with the OAuth client as well.

Testing a credential

Both credential types have a built-in test that calls GET /me. Click Save and n8n reports whether the connection works, which plan the account is on and which scopes the token carries.

Empirio node

Choose a Resource, then an Operation. Surveys are picked from a searchable dropdown, or addressed by survey URL or ID.

Survey

Operation	Description
Create	Create a draft, either from a prompt (`AI` mode) or from explicit questions (`Manual` mode)
Delete	Permanently delete a survey
Duplicate	Copy a survey into a new unpublished draft
Get	Read one survey including its questions and settings
Get Many	List surveys owned by or shared with the account
Get Questions	The question definitions used by the analytics operations
Get Stats	View count, started and completed responses, completion rate and completion time
Publish	Publish the working draft and return the public survey URL
Unpublish	Take a survey offline and move it back to draft
Update	Apply changes to the working draft without publishing

Get returns 13 fields, two of which are whole trees. Its Output parameter chooses between Simplified (everything except the question list and design settings — the default), Raw, and Selected Fields, which returns only what you pick plus the survey ID. The parameter exists because the node is usable as an AI tool, where handing a model a full survey definition spends its context for no gain.

Get Questions and Get Stats call endpoints that sit under /responses/ in the REST API but describe the survey rather than individual responses, which is why they live here.

Create and Update both accept an AI mode, where empirio generates the change from a prompt, and a Manual mode, where the node sends exactly what you give it. Manual mode takes the deeply structured sections — questions, question operations, option operations, logic rules, settings and translations — as JSON, so they can be built with expressions from earlier nodes.

Response

Operation	Description
Export	Export responses (CSV, XLSX, JSON, SPSS) or charts (PowerPoint, PDF, DOCX, ZIP of images, chart JSON) and return a temporary download URL
Get Aggregates	Per-question answer counts and percentages
Get Crosstab	Cross-tabulate the answers of two questions
Get Many	List participations with their answers

Get Many pages through the API automatically when Return All is on. Its Since option takes an ISO timestamp and returns only responses submitted after it, which makes a scheduled polling workflow straightforward when a webhook is not an option.

The question dropdowns of Get Aggregates and Get Crosstab are filled from the survey you selected, so you never have to look up a question ID by hand.

empirio.ai Trigger

The trigger registers a webhook on the selected survey when the workflow is activated, and removes it again when the workflow is deactivated. Every delivery is signed with a per-webhook secret, and the trigger verifies the X-Empirio-Signature HMAC before it emits anything. A delivery with a missing or wrong signature is answered with HTTP 401 and never starts the workflow. empirio treats any 2xx as delivered, so answering 401 is what makes it retry and then surface a failed delivery — a silent 200 would discard the response and leave both sides reporting success.

Output controls the shape of the emitted item:

Flat Answers (default) — one item per response with the label-resolved answers keyed by question ID, next to the response metadata (response_id, responded_at, survey_id, duration_seconds, …). This is what most workflows want: map it straight into a spreadsheet row, a CRM record or a database column set.
Full Payload — the complete delivery, including the per-cell answers array that mirrors the CSV export layout (one entry per checkbox option, matrix row, rank position and free-text companion).

Options → Label sets the name shown for the webhook in the empirio dashboard. It defaults to the workflow name.

Question IDs are stable for the lifetime of a survey. Inserting, removing or reordering questions never shifts an existing ID, so a mapping you build once keeps working, and the same ID also identifies the question in the Empirio node's analytics operations.

Recovering a lost registration

If a workflow is imported, duplicated or restored, n8n may no longer hold the webhook state. On the next activation the trigger looks up the survey's webhooks, matches its own callback URL and adopts the existing registration. Because empirio hands out a webhook's signing secret only once, the trigger rotates the secret in that case so it can verify deliveries again. Rotating affects only this registration — other webhooks on the survey are untouched.

Self-hosted and Cloud

empirio only delivers to endpoints it can reach:

The endpoint must be HTTPS. Plain http:// URLs are rejected.
Endpoints resolving to private or loopback addresses are rejected, so localhost and 192.168.x.x do not work.

n8n Cloud satisfies both conditions out of the box — the empirio.ai Trigger works with no extra setup.

Self-hosted n8n needs a publicly reachable HTTPS host name. Set WEBHOOK_URL to that public URL so n8n hands the correct address to empirio, and put a TLS-terminating reverse proxy or tunnel in front of the instance. During local development, n8n started through a tunnel works as well.

The Empirio node itself has no such requirement — it makes outbound calls only and works on any n8n instance with internet access.

Rate limits and idempotency

The empirio API allows 60 read and 20 write requests per minute per token. When a limit is hit the API answers 429 with a Retry-After header; enable Retry On Fail on the node to have n8n back off and try again.

Every write carries an Idempotency-Key, so a retried request is applied at most once. The node generates a fresh key per request by default. Set the Idempotency Key field — usually from an expression such as an order or ticket ID — when several executions must collapse into a single change. Keys are remembered for 24 hours.