{"site":{"name":"Koji","description":"AI-native customer research platform that helps teams conduct, analyze, and synthesize customer interviews at scale.","url":"https://www.koji.so","contentTypes":["blog","documentation"],"lastUpdated":"2026-09-21T05:54:36.800Z"},"content":[{"type":"documentation","id":"adb8b15e-2219-4da4-a6f6-3aa081c1744b","slug":"n8n-research-automation","title":"Connect Koji to n8n: Build Self-Hosted Customer Research Pipelines","url":"https://www.koji.so/docs/n8n-research-automation","summary":"Connect Koji to n8n with a Schedule Trigger that polls the Koji read endpoint for completed interviews, then route the payloads to Notion, Linear, Slack, HubSpot, Salesforce, or any of n8n's 400+ integrations. Koji has no outbound webhooks yet, so the completion signal comes from polling, or from the embed widget's koji:interview_completed event when the interview runs inside an embed. A completed interview carries the full analysis (quality score, themes, sentiment, structured answers, respondent metadata). n8n's self-hosting model keeps interview data on infrastructure you control — the key advantage over Zapier and Make for teams with data residency or compliance constraints. Setup takes ~15 minutes end to end.","content":"**TL;DR:** Connect Koji to [n8n](https://n8n.io) and every completed AI interview can trigger a custom self-hosted workflow: create a Linear ticket from a low-quality-score conversation, route Enterprise-segment feedback to a Slack channel, append the transcript to a Notion database, score sentiment in a CRM record, or fan out to a dozen downstream tools at once. Setup takes about 15 minutes: add a Schedule Trigger in n8n, call the Koji read endpoint with an HTTP Request node, keep the interviews that have finished and been analysed, and map the payload into any of n8n's 400+ integrations. The big advantage over Zapier or Make is data residency: n8n runs on infrastructure you control, so interview transcripts never leave your stack.\n\n---\n\n## Why n8n + Koji Is a Powerful Combination\n\nMost research automation platforms (Zapier, Make) live in a vendor cloud. That is fine for marketing automation but creates a real problem for customer interview data, which often contains PII, business-sensitive feedback, and direct customer quotes that compliance teams want on infrastructure the organization owns.\n\nn8n is the leading open-source workflow automation platform. You can self-host it on your own Kubernetes cluster, a single VPS, or even a Raspberry Pi for personal projects, and your data never traverses a SaaS automation vendor. It still gives you 400+ pre-built integrations — Notion, Linear, Jira, Slack, HubSpot, Salesforce, Airtable, Google Sheets, Postgres, S3, and so on — and a drag-and-drop visual editor.\n\nCombining n8n with Koji's API-driven AI research platform gives you the best of both worlds:\n\n- **AI-native research collection** — Koji runs the conversational interview, transcribes voice, scores quality, extracts themes, and exposes a fully analyzed payload on the read endpoint the moment each interview completes.\n- **Self-hosted routing logic** — n8n decides where the data goes, how it is filtered, what it is enriched with, and which downstream systems are notified.\n\nTraditional research platforms (SurveyMonkey, Qualtrics) cannot do this — they offer at most a \"send to email\" notification. Tools like Koji are designed API-first, which is why a five-node n8n workflow can replace a thousand-dollar custom integration project.\n\n---\n\n## Prerequisites\n\nBefore you start:\n\n1. **A running n8n instance.** Either self-hosted (Docker, Kubernetes, or the official npm package) or n8n Cloud. The Webhook node works identically in both.\n2. **A Koji project with at least one published study.** [Create one](/docs/creating-your-first-study) if you have not — the free plan includes enough credits to run a test interview.\n3. **A Koji API key.** Generate from **Settings → API Keys → Create API Key** in the Koji web app. Store it in n8n's credentials manager.\n4. **A target destination tool.** For this guide we walk through Notion + Linear + Slack, but the same pattern works for any n8n node.\n\n---\n\n## Architecture: How the Pipeline Works\n\n```\nParticipant completes Koji interview\n        │\n        ▼\nKoji analysis pipeline runs (quality score, themes, structured answers, sentiment)\n        │\n        ▼\nn8n Schedule Trigger polls GET /api/v1/interviews/{id} for pending interviews\n        │\n        ▼\nn8n keeps the ones that are completed with analysis present\n        │\n        ▼\nn8n routes by quality/sentiment/segment via IF / Switch nodes\n        │\n        ├─→ Notion: append page with transcript + themes\n        ├─→ Linear: create ticket if quality_score < 3 (low signal needs review)\n        ├─→ Slack: alert the CS team for Enterprise segment\n        └─→ HubSpot: enrich the contact record with sentiment\n```\n\nThe whole flow is fully asynchronous. Koji does not block waiting for n8n to finish, and n8n can fan out to dozens of destinations in parallel.\n\n---\n\n## Step 1: Create the n8n Schedule Trigger\n\nKoji has no outbound webhooks yet, so n8n pulls rather than waiting to be pushed. In your n8n canvas:\n\n1. Click **Add first step** → choose **Schedule Trigger**.\n2. Set the interval to every minute, or every 15 minutes if near real time is not needed.\n3. Add an **HTTP Request** node: `GET https://www.koji.so/api/v1/interviews/{{ $json.interview_id }}` with an `Authorization: Bearer YOUR_KOJI_API_KEY` header.\n4. Feed it the interview ids you stored when the interviews were started, from a Postgres node, a Redis node, or n8n's own static data.\n5. Click **Test step** to capture a sample payload.\n\nIf your interviews run in the embed widget, the browser's `koji:interview_completed` event is a faster signal you can forward to an n8n Webhook node of your own. Polling stays the safety net.\n\n---\n\n## Step 2: Create a Koji API key\n\nSwitch to the Koji web app:\n\n1. Open your study → **Settings → API Keys**.\n2. Click **Create API Key** and give it the `interview:read` permission.\n3. Copy the key once and store it in n8n's credentials manager or an environment variable.\n4. Note the study id. API keys are study scoped, so one key reads one study.\n\nSee [Webhook Setup](/docs/webhook-setup) for the completion patterns that exist today and the payload format.\n\n---\n\n## Step 3: Keep Only Newly Completed Interviews\n\nAdd a **Function** node after the HTTP Request node and paste:\n\n```javascript\n// Runs once per polled interview. Keep only the interviews that are\n// finished, analysed, and not already routed.\nconst interview = $input.first().json;\n\nif (interview.status !== 'completed' || !interview.analysis) {\n  return []; // not ready yet, the next run picks it up\n}\n\nconst store = $getWorkflowStaticData('global');\nstore.processed = store.processed || {};\n\nif (store.processed[interview.interview_id]) {\n  return []; // already routed, do not write it twice\n}\nstore.processed[interview.interview_id] = true;\n\nreturn interview;\n```\n\nStore the Koji API key in n8n's environment variables (or in the credentials manager for n8n Cloud). Never paste it directly into a node, because it ends up in the workflow export.\n\nThis step is essential. `analysis` is null until the background analysis job has finished, so gating on completed plus analysis means a pass only ever picks up fully processed interviews. The dedupe key stops the same interview being written to your downstream systems twice.\n\n---\n\n## Step 4: Route by Quality, Segment, or Sentiment\n\nAdd a **Switch** node after the Function node. Configure rules that branch on the payload:\n\n- Branch 1: `{{ $json.data.quality_score >= 4 }}` → high-signal interviews\n- Branch 2: `{{ $json.data.quality_score < 3 }}` → low-signal interviews that need researcher review\n- Branch 3: `{{ $json.data.metadata.segment === 'enterprise' }}` → Enterprise segment alerts\n\nEach branch flows to a different destination node.\n\n---\n\n## Step 5: Fan Out to Destinations\n\n### Notion: Append a Page With Transcript\n\nAdd a **Notion** node:\n\n- Operation: **Create Page**\n- Database: select your research repository database\n- Properties: map `Name` → `{{ $json.data.respondent.display_name }}`, `Quality` → `{{ $json.data.quality_score }}`, `Segment` → `{{ $json.data.metadata.segment }}`\n- Body: add a **Heading** with the interview title, then a **Toggle** containing the AI-generated summary, and a **Code Block** containing the structured answers JSON\n\nTo pull the full transcript and the structured analysis (themes, sentiment, all answers), add an **HTTP Request** node before the Notion node:\n\n```\nGET https://www.koji.so/api/v1/interviews/{{ $json.data.interview_id }}\nAuthorization: Bearer YOUR_KOJI_API_KEY\n```\n\nUse the response to populate richer Notion fields. See [User Research API](/docs/user-research-api-guide) for the full endpoint.\n\n### Linear: Create a Ticket for Low-Quality Interviews\n\nIn the low-quality branch, add a **Linear** node:\n\n- Operation: **Create Issue**\n- Team: your research-ops team\n- Title: `Low-signal interview — review needed (quality {{ $json.data.quality_score }})`\n- Description: include the transcript URL `https://www.koji.so/projects/{{ $json.data.project_id }}/interviews/{{ $json.data.interview_id }}`\n- Labels: `research-qa`, the segment, the study slug\n\nThis is how research-ops teams catch interview design issues before they propagate — if quality scores trend low for one question, that question needs revision.\n\n### Slack: Alert on Enterprise Feedback\n\nIn the Enterprise-segment branch, add a **Slack** node:\n\n- Operation: **Post Message**\n- Channel: `#cs-enterprise-feedback`\n- Text: `New Enterprise interview from {{ $json.data.respondent.display_name }} ({{ $json.data.metadata.company }}). Quality {{ $json.data.quality_score }}. <https://www.koji.so/projects/{{ $json.data.project_id }}/interviews/{{ $json.data.interview_id }}|Open transcript>`\n\nCS leads love this pattern. Enterprise feedback gets human eyes within minutes of the interview ending.\n\n---\n\n## Step 6: Test the Pipeline End-to-End\n\nRun a preview interview in your study so there is a completed interview to read, then click **Execute Workflow** in n8n.\n\nWatch n8n's executions list. You should see:\n\n1. Schedule Trigger fired and the HTTP Request node fetched the interview.\n2. Function node let it through: completed, analysed, and not seen before.\n3. Switch node routed to the correct branch.\n4. Destination nodes executed without error.\n\nThen run a real interview through your published study and confirm a real participant's data lands in Notion / Linear / Slack. The end-to-end latency from interview-end to Notion-page is typically one to two minutes, set by Koji's analysis pipeline plus your poll interval.\n\n---\n\n## Patterns That Scale\n\n### Idempotency\n\nPoll passes overlap, and workflows get re-run by hand (see [Webhook Setup](/docs/webhook-setup)). Make destination steps idempotent: use the `interview_id` as the Notion page ID lookup key, Linear external ID, etc. n8n's **Get Many** + **If exists** pattern works well.\n\n### Backpressure\n\nIf you run a high-volume study (1000+ interviews/day), put a **Queue** node (Redis or RabbitMQ) between the Function node and your destinations. n8n will then drain the queue at a controlled rate that respects downstream API limits.\n\n### Enrichment\n\nAdd an HTTP Request node to call your own internal services with the respondent's email or external ID to enrich the payload with internal data (plan tier, ARR, account manager). This lets downstream destinations include business context the participant did not provide directly.\n\n### Reverse Trigger\n\nThe pattern also works in the other direction. Use n8n to trigger Koji studies — a Linear ticket marked \"needs customer validation\" can call `POST /api/v1/interviews/start` to open an interview for a chosen customer, send them the link with your own email tool, and feed the result back into the original ticket as a comment.\n\n---\n\n## n8n vs. Other Automation Platforms\n\n- **vs. [Zapier](/docs/zapier-research-automation):** Zapier has the largest pre-built app catalog and is the fastest path for non-technical teams. n8n is the right pick when data residency matters, when costs at high volume become a concern (Zapier bills per task), or when you want to self-host.\n- **vs. Make.com:** Similar trade-off — Make has visual scenarios but is cloud-only. n8n adds self-hosting and a more flexible node-based runtime with full JavaScript Function nodes.\n- **vs. Custom code:** A custom webhook handler is more flexible than any visual tool but takes longer to build and maintain. n8n hits the sweet spot for most teams.\n\nFor Notion-specific workflows, see [Sync Koji to Notion](/docs/notion-research-integration). For Zapier specifically, see [Zapier Research Automation](/docs/zapier-research-automation).\n\n---\n\n## Security Checklist\n\n- **Keep the Koji API key server side.** A polling workflow needs only the `interview:read` permission. See the Function node code in Step 3.\n- **Use environment variables or the credentials manager** for the Koji API key. Never inline it.\n- **Restrict any n8n Webhook node you add** for forwarded embed events. Use a long, random string in the path so it cannot be guessed and replayed.\n- **Run n8n over HTTPS.** The Koji API is HTTPS only and your key travels in the Authorization header.\n- **Rotate the Koji API key periodically** from **Settings → API Keys**. Revoke any key whose origin is no longer trusted.\n\n---\n\n## Related Resources\n\n- [Webhook Setup](/docs/webhook-setup): the completion patterns that exist today, polling and payload format\n- [Research Automation Webhooks](/docs/research-automation-webhooks) — design patterns for real-time research pipelines\n- [Zapier Research Automation](/docs/zapier-research-automation) — the cloud alternative to n8n\n- [Sync Koji to Notion](/docs/notion-research-integration) — Notion-specific recipe\n- [User Research API](/docs/user-research-api-guide) — full REST surface for enrichment and reverse triggers\n- [Structured Questions Guide](/docs/structured-questions-guide) — the 6 question types whose answers land in your pipeline\n- [Exporting Research Data](/docs/exporting-research-data) — CSV and JSON exports for batch workflows\n- [API Authentication](/docs/api-authentication) — generating, rotating, and revoking Koji API keys","category":"API Reference","lastModified":"2026-09-20T18:39:45.368196+00:00","metaTitle":"Connect Koji to n8n: Self-Hosted Customer Research Pipelines | Koji Docs","metaDescription":"Build self-hosted research automation with n8n + Koji. Poll the Koji API on a schedule and route every interview to Notion, Linear, Slack, or your CRM.","keywords":["koji n8n integration","n8n research automation","self-hosted research pipeline","koji webhook n8n","n8n customer research","research workflow automation n8n"],"aiSummary":"Connect Koji to n8n with a Schedule Trigger that polls the Koji read endpoint for completed interviews, then route the payloads to Notion, Linear, Slack, HubSpot, Salesforce, or any of n8n's 400+ integrations. Koji has no outbound webhooks yet, so the completion signal comes from polling, or from the embed widget's koji:interview_completed event when the interview runs inside an embed. A completed interview carries the full analysis (quality score, themes, sentiment, structured answers, respondent metadata). n8n's self-hosting model keeps interview data on infrastructure you control — the key advantage over Zapier and Make for teams with data residency or compliance constraints. Setup takes ~15 minutes end to end.","aiPrerequisites":["Running n8n instance (self-hosted or n8n Cloud)","Koji project with at least one published study","Koji API key from Settings → API Keys","A destination tool to route data into (Notion, Linear, Slack, etc.)"],"aiLearningOutcomes":["Build an end-to-end n8n pipeline from Koji to your tools","Poll the Koji read endpoint and dedupe completed interviews","Route interviews by quality, segment, or sentiment","Fan out to Notion, Linear, Slack, and CRMs in parallel","Apply production patterns for idempotency, backpressure, and enrichment"],"aiDifficulty":"intermediate","aiEstimatedTime":"15 min"}],"pagination":{"total":1,"returned":1,"offset":0}}