{"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-05-31T08:55:27.026Z"},"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 by registering an n8n Webhook node URL as a Koji webhook destination, verifying the X-Koji-Signature HMAC-SHA256 signature in a Function node using the webhook secret, then routing payloads to Notion, Linear, Slack, HubSpot, Salesforce, or any of n8n's 400+ integrations. The interview.analysis_ready event delivers fully analyzed payloads (quality score, themes, sentiment, structured answers, respondent metadata) within seconds of an interview completing. 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 — generate a Webhook node URL in n8n, add it as a webhook destination in your Koji study, verify the HMAC signature in a Function node, 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 webhook-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 emits a fully analyzed payload 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 webhook-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        ▼\nKoji webhook POSTs payload to your n8n Webhook node\n        │\n        ▼\nn8n verifies HMAC signature\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 Webhook Trigger\n\nIn your n8n canvas:\n\n1. Click **Add first step** → choose **Webhook**.\n2. Set HTTP method to `POST`.\n3. Set Path to something memorable like `koji-interview-completed`.\n4. Set Authentication to **None** (we will verify with HMAC in code instead — more secure than basic auth).\n5. Set Response Mode to `Immediately` so n8n returns `200` before doing the work. Koji webhooks must be acknowledged within 10 seconds or they retry.\n6. Click **Test step** to capture a sample payload. n8n shows you the production webhook URL — copy it.\n\nThe URL looks like `https://your-n8n.example.com/webhook/koji-interview-completed` if self-hosted, or `https://your-instance.app.n8n.cloud/webhook/koji-interview-completed` on n8n Cloud.\n\n---\n\n## Step 2: Register the Webhook in Koji\n\nSwitch to the Koji web app:\n\n1. Open your study → **Settings → Integrations → Webhooks**.\n2. Click **Add Webhook Endpoint**.\n3. Paste the n8n URL from Step 1.\n4. Subscribe to `interview.analysis_ready` — this is the event with the full analyzed payload.\n5. Optionally also subscribe to `interview.quality_scored` if you want a separate stream for quality routing.\n6. Click **Save**. Koji sends a verification request — n8n's Webhook node returns `200` immediately so the registration succeeds.\n7. Copy the **Webhook Secret** that Koji displays. You will need it for signature verification in n8n.\n\nSee [Webhook Setup](/docs/webhook-setup) for the full list of events and payload format.\n\n---\n\n## Step 3: Verify the HMAC Signature\n\nAdd a **Function** node after the Webhook node and paste:\n\n```javascript\nconst crypto = require('crypto');\n\nconst rawBody = JSON.stringify($input.first().json.body);\nconst signatureHeader = $input.first().json.headers['x-koji-signature'];\nconst secret = $env.KOJI_WEBHOOK_SECRET; // store secret in n8n env vars\n\nif (!signatureHeader) {\n  throw new Error('Missing X-Koji-Signature header');\n}\n\nconst expected = 'sha256=' + crypto\n  .createHmac('sha256', secret)\n  .update(rawBody)\n  .digest('hex');\n\nconst valid = crypto.timingSafeEqual(\n  Buffer.from(signatureHeader),\n  Buffer.from(expected)\n);\n\nif (!valid) {\n  throw new Error('Invalid Koji webhook signature');\n}\n\nreturn $input.first().json.body;\n```\n\nSet `KOJI_WEBHOOK_SECRET` in n8n's environment variables (or in the credentials manager for n8n Cloud). Never paste the secret directly into the Function node — it ends up in the workflow export.\n\nThis step is essential. Without signature verification, anyone who learns the n8n webhook URL can replay forged events and pollute your downstream systems. Koji signs every outbound webhook with `X-Koji-Signature: sha256=...` using HMAC-SHA256 over the raw body.\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 verified 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\nBack in the Koji web app, on the webhook endpoint card, click **Send Test Event**. Koji sends a fully formed sample payload with a valid signature.\n\nWatch n8n's executions list. You should see:\n\n1. Webhook node received the POST.\n2. Function node verified the signature (no error thrown).\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 30–90 seconds, dominated by Koji's analysis pipeline.\n\n---\n\n## Patterns That Scale\n\n### Idempotency\n\nKoji may retry a webhook if your endpoint did not respond within 10 seconds (see [Webhook Setup](/docs/webhook-setup) for the full retry policy). 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/studies/{id}/invite` to send an interview link to selected customers 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- **Verify signatures on every webhook.** No exceptions. See the Function node code in Step 3.\n- **Use environment variables or the credentials manager** for the Koji webhook secret and API key. Never inline them.\n- **Restrict the n8n Webhook node's path.** Use a long, random string in the path so it cannot be guessed and replayed.\n- **Run n8n over HTTPS.** Koji refuses to deliver webhooks to plain HTTP endpoints.\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) — events, payload format, signature verification, retry policy\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-05-31T03:26:43.116998+00:00","metaTitle":"Connect Koji to n8n: Self-Hosted Customer Research Pipelines | Koji Docs","metaDescription":"Build self-hosted research automation with n8n + Koji. Route every interview to Notion, Linear, Slack, or your CRM. Includes HMAC verification code and routing patterns.","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 by registering an n8n Webhook node URL as a Koji webhook destination, verifying the X-Koji-Signature HMAC-SHA256 signature in a Function node using the webhook secret, then routing payloads to Notion, Linear, Slack, HubSpot, Salesforce, or any of n8n's 400+ integrations. The interview.analysis_ready event delivers fully analyzed payloads (quality score, themes, sentiment, structured answers, respondent metadata) within seconds of an interview completing. 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","Verify Koji webhook HMAC signatures securely","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}}