Connect Koji to n8n: Build Self-Hosted Customer Research Pipelines

TL;DR: Connect Koji to n8n 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.

---

Why n8n + Koji Is a Powerful Combination

Most 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.

n8n 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.

Combining n8n with Koji's webhook-driven AI research platform gives you the best of both worlds:

• 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.
• 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.

Traditional 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.

---

Prerequisites

Before you start:

1. A running n8n instance. Either self-hosted (Docker, Kubernetes, or the official npm package) or n8n Cloud. The Webhook node works identically in both.
2. A Koji project with at least one published study. Create one if you have not — the free plan includes enough credits to run a test interview.
3. A Koji API key. Generate from Settings → API Keys → Create API Key in the Koji web app. Store it in n8n's credentials manager.
4. A target destination tool. For this guide we walk through Notion + Linear + Slack, but the same pattern works for any n8n node.

---

Architecture: How the Pipeline Works

Participant completes Koji interview
        │
        ▼
Koji analysis pipeline runs (quality score, themes, structured answers, sentiment)
        │
        ▼
Koji webhook POSTs payload to your n8n Webhook node
        │
        ▼
n8n verifies HMAC signature
        │
        ▼
n8n routes by quality/sentiment/segment via IF / Switch nodes
        │
        ├─→ Notion: append page with transcript + themes
        ├─→ Linear: create ticket if quality_score < 3 (low signal needs review)
        ├─→ Slack: alert the CS team for Enterprise segment
        └─→ HubSpot: enrich the contact record with sentiment

The 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.

---

Step 1: Create the n8n Webhook Trigger

In your n8n canvas:

1. Click Add first step → choose Webhook.
2. Set HTTP method to POST.
3. Set Path to something memorable like koji-interview-completed.
4. Set Authentication to None (we will verify with HMAC in code instead — more secure than basic auth).
5. Set Response Mode to Immediately so n8n returns 200 before doing the work. Koji webhooks must be acknowledged within 10 seconds or they retry.
6. Click Test step to capture a sample payload. n8n shows you the production webhook URL — copy it.

The 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.

---

Step 2: Register the Webhook in Koji

Switch to the Koji web app:

1. Open your study → Settings → Integrations → Webhooks.
2. Click Add Webhook Endpoint.
3. Paste the n8n URL from Step 1.
4. Subscribe to interview.analysis_ready — this is the event with the full analyzed payload.
5. Optionally also subscribe to interview.quality_scored if you want a separate stream for quality routing.
6. Click Save. Koji sends a verification request — n8n's Webhook node returns 200 immediately so the registration succeeds.
7. Copy the Webhook Secret that Koji displays. You will need it for signature verification in n8n.

See Webhook Setup for the full list of events and payload format.

---

Step 3: Verify the HMAC Signature

Add a Function node after the Webhook node and paste:

const crypto = require('crypto');

const rawBody = JSON.stringify($input.first().json.body);
const signatureHeader = $input.first().json.headers['x-koji-signature'];
const secret = $env.KOJI_WEBHOOK_SECRET; // store secret in n8n env vars

if (!signatureHeader) {
  throw new Error('Missing X-Koji-Signature header');
}

const expected = 'sha256=' + crypto
  .createHmac('sha256', secret)
  .update(rawBody)
  .digest('hex');

const valid = crypto.timingSafeEqual(
  Buffer.from(signatureHeader),
  Buffer.from(expected)
);

if (!valid) {
  throw new Error('Invalid Koji webhook signature');
}

return $input.first().json.body;

Set 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.

This 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.

---

Step 4: Route by Quality, Segment, or Sentiment

Add a Switch node after the Function node. Configure rules that branch on the verified payload:

• Branch 1: {{ $json.data.quality_score >= 4 }} → high-signal interviews
• Branch 2: {{ $json.data.quality_score < 3 }} → low-signal interviews that need researcher review
• Branch 3: {{ $json.data.metadata.segment === 'enterprise' }} → Enterprise segment alerts

Each branch flows to a different destination node.

---

Step 5: Fan Out to Destinations

Notion: Append a Page With Transcript

Add a Notion node:

• Operation: Create Page
• Database: select your research repository database
• Properties: map Name → {{ $json.data.respondent.display_name }}, Quality → {{ $json.data.quality_score }}, Segment → {{ $json.data.metadata.segment }}
• 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

To pull the full transcript and the structured analysis (themes, sentiment, all answers), add an HTTP Request node before the Notion node:

GET https://www.koji.so/api/v1/interviews/{{ $json.data.interview_id }}
Authorization: Bearer YOUR_KOJI_API_KEY

Use the response to populate richer Notion fields. See User Research API for the full endpoint.

Linear: Create a Ticket for Low-Quality Interviews

In the low-quality branch, add a Linear node:

• Operation: Create Issue
• Team: your research-ops team
• Title: Low-signal interview — review needed (quality {{ $json.data.quality_score }})
• Description: include the transcript URL https://www.koji.so/projects/{{ $json.data.project_id }}/interviews/{{ $json.data.interview_id }}
• Labels: research-qa, the segment, the study slug

This is how research-ops teams catch interview design issues before they propagate — if quality scores trend low for one question, that question needs revision.

Slack: Alert on Enterprise Feedback

In the Enterprise-segment branch, add a Slack node:

• Operation: Post Message
• Channel: #cs-enterprise-feedback
• 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>

CS leads love this pattern. Enterprise feedback gets human eyes within minutes of the interview ending.

---

Step 6: Test the Pipeline End-to-End

Back 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.

Watch n8n's executions list. You should see:

1. Webhook node received the POST.
2. Function node verified the signature (no error thrown).
3. Switch node routed to the correct branch.
4. Destination nodes executed without error.

Then 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.

---

Patterns That Scale

Idempotency

Koji may retry a webhook if your endpoint did not respond within 10 seconds (see 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.

Backpressure

If 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.

Enrichment

Add 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.

Reverse Trigger

The 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.

---

n8n vs. Other Automation Platforms

• vs. Zapier: 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.
• 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.
• 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.

For Notion-specific workflows, see Sync Koji to Notion. For Zapier specifically, see Zapier Research Automation.

---

Security Checklist

• Verify signatures on every webhook. No exceptions. See the Function node code in Step 3.
• Use environment variables or the credentials manager for the Koji webhook secret and API key. Never inline them.
• Restrict the n8n Webhook node's path. Use a long, random string in the path so it cannot be guessed and replayed.
• Run n8n over HTTPS. Koji refuses to deliver webhooks to plain HTTP endpoints.
• Rotate the Koji API key periodically from Settings → API Keys. Revoke any key whose origin is no longer trusted.

---

Related Resources

• Webhook Setup — events, payload format, signature verification, retry policy
• Research Automation Webhooks — design patterns for real-time research pipelines
• Zapier Research Automation — the cloud alternative to n8n
• Sync Koji to Notion — Notion-specific recipe
• User Research API — full REST surface for enrichment and reverse triggers
• Structured Questions Guide — the 6 question types whose answers land in your pipeline
• Exporting Research Data — CSV and JSON exports for batch workflows
• API Authentication — generating, rotating, and revoking Koji API keys