Back to docs
API Reference

Send Koji Insights to Linear: Auto-File Engineering Tickets from Customer Interviews

Wire Koji to Linear so a customer interview that surfaces a real problem opens a Linear issue with the AI summary, key insights, quality score and a link back to the interview. Koji pushes a signed interview.completed webhook when each interview is scored, and Zapier or a small receiver turns it into an issue.

TL;DR: Connect Koji to Linear so a customer interview that surfaces a real problem opens a Linear issue with the AI summary, the key insights, the quality score and a link back to the interview. Koji pushes a signed interview.completed webhook the moment an interview is finished and scored, so there's nothing to poll. Setup takes about 20 minutes with Zapier, or half a day if you build the receiver yourself against Linear's GraphQL API.

Why teams sync Koji to Linear

Linear is where engineering work happens. Tickets there get triaged, planned and shipped, so anything that wants to shape the roadmap has to live there. Research findings that never reach Linear rarely reach the roadmap.

The usual flow is slow and lossy: a PM reads an interview, takes notes, writes a ticket from memory, and engineering reads it without the context. By the time the feature ships, the link back to what the customer actually said is gone.

A Koji to Linear sync replaces that chain. When an interview finishes, Koji sends your endpoint a webhook. Your Zap (or your own receiver) checks the quality score, fetches the interview's analysis, and opens a Linear issue containing:

  • Koji's AI summary of the interview
  • The key insights, as a list
  • The overall sentiment (positive, negative or mixed)
  • The quality score and level, so engineering can weigh the signal
  • The study name and interview mode (text, voice or phone)
  • A direct link to the interview in Koji, where anyone on the team can read the transcript

What Koji sends, and what you fetch

Two pieces of the Koji API do the work. Knowing which field lives where saves most of the debugging.

The webhook (interview.completed) arrives when an interview is finished and scored. It is small on purpose:

FieldWhat it holds
data.interview_id, data.study_id, data.study_nameWhich interview and study
data.modetext, voice or phone
data.participant.external_idYour own ID for the person, if you passed one in (null for panel participants)
data.trust.quality_scoreThe interview's quality score, 1 to 5
data.trust.quality_levelShallow, Fair, Good or Excellent
data.trust.meets_quality_barTrue when the interview counts towards the report
data.trust.fraud_riskhigh, medium, low or unknown
data.links.appThe interview in Koji
data.links.apiThe read endpoint for this interview

The read endpoint (GET on data.links.api, with your study's API key) returns the full interview: the transcript, respondent details, stats and, once analysis has run, analysis.summary, analysis.key_insights and analysis.sentiment. Because the webhook only fires after scoring, the analysis is normally ready by the time you fetch it.

The webhook doesn't carry themes or quotes. Study-level themes live in the report, not on each interview. If you want a verbatim quote in the ticket, take it from the transcript in the read response.

Integration paths

  1. Zapier (recommended): point and click, about 20 minutes, no code
  2. Your own receiver plus Linear's GraphQL API (advanced): verify the signature yourself, then call Linear directly

Start with Zapier. Build your own receiver once you need signature checks, richer formatting or high volume.

Prerequisites

  • A Koji study with at least one completed interview
  • A paid Koji plan. Webhooks are on Insights, Interviews and Enterprise. Fetching the analysis needs a study API key, which comes with Interviews and Enterprise.
  • A Linear workspace where you can create issues in at least one team
  • A Zapier account on a plan that includes webhooks and filters
  • About 20 minutes

Step 1: Decide which interviews become tickets

This is the decision that matters most, and the one teams skip. Don't open a Linear ticket for every interview: the backlog fills up and engineering stops reading them within a week.

Rules that work:

  • Quality first. Only continue when meets_quality_bar is true, and usually only when quality_score is 4 or higher (Good or Excellent). This drops thin and accidental sessions.
  • Drop risky sessions. Skip anything with fraud_risk set to high.
  • Negative sentiment. After fetching the analysis, continue only when analysis.sentiment is negative or mixed. Happy interviews rarely need a ticket.
  • Keywords in the insights. Continue only when a key insight mentions words your team cares about ("bug", "slow", "can't", "missing", "error").
  • Combine them. "Quality 4 or higher AND sentiment negative" is a good default.

Write the rule down before you build. You can change it later, but a default stops the first-day flood.

Step 2: Add the webhook in Koji

In Koji, open the study, then Integrate, then Webhooks:

  1. Paste the Zapier hook URL from Step 3 as the endpoint URL (create the Zap first, or come back to this step)
  2. Subscribe to interview.completed
  3. Choose this study, or every study including new ones
  4. Copy the signing secret somewhere safe
  5. Send a test event and check the delivery log shows a 2xx answer
Process showing six steps to set up a Koji webhook, from opening Integrate to sending a test event and watching the delivery log.
The same six steps work for any destination, Linear included · Download or share

Every message is signed, retried for up to 24 hours if your endpoint is down, and kept in a delivery log you can resend from. Give this to your AI copies a full brief a coding assistant can use to build a receiver. Full reference: Webhook Setup.

Also create a study API key (see API authentication). Zapier uses it to fetch the analysis.

Step 3: Create the Zap

In Zapier:

  1. New Zap, trigger Webhooks by Zapier: Catch Hook. Copy the hook URL into Koji (Step 2) and send a test event so Zapier sees a sample.
  2. Add Filter by Zapier: the top-level type equals interview.completed, data.trust.meets_quality_bar is true, data.trust.quality_score is at least 4, and data.trust.fraud_risk is not high.
  3. Add Webhooks by Zapier: GET to the URL in data.links.api, with the header Authorization: Bearer <your study API key>.
  4. Add a second filter on the GET result, for example analysis.sentiment is negative or mixed.

Zapier's Catch Hook doesn't check Koji's signature. That's fine for a low-risk ticket flow, because the GET step only succeeds with your own API key against a real interview. If you need signature checks, use the receiver path below.

Step 4: Create the Linear issue

Add Linear: Create Issue and connect your workspace. Configure:

  • Team: the team that owns this part of the product
  • Title: [Research] {data.study_name}: {first item of analysis.key_insights}. Truncate to keep it short.
  • Description (Linear supports markdown):
**Summary:** {analysis.summary}

**Key insights:**
{analysis.key_insights, one per line}

**Sentiment:** {analysis.sentiment}
**Quality:** {data.trust.quality_level} ({data.trust.quality_score}/5)
**Study:** {data.study_name} ({data.mode} interview)
**Customer ID:** {data.participant.external_id}

**Read the interview in Koji:** {data.links.app}

---
Filed from Koji. Edit or close if not actionable.
  • Labels: a fixed research label, plus one per study or product area if you route by study
  • Priority: leave it to triage. Quality says how good the answers were, not how serious the problem is. If you want an automatic hint, set a higher priority when sentiment is negative.
  • Assignee: empty, so triage picks it up

Send a test through the whole Zap. The issue should land in the team's triage within seconds.

Step 5: Turn it on and tune

Switch the Zap on and watch it for a week. The usual fix is a stricter filter: raise the quality bar or narrow the keyword list.

Patterns that pay off

One issue per problem, not per interview

Add a Linear: Find Issue step before Create Issue, searching open issues in the team by a keyword from the insight. If one exists, add a comment with the new summary and link instead of a duplicate. The same pain heard in ten interviews becomes one issue with ten pieces of evidence.

Route by study

Point each study's webhook at its own Zap, or use Zapier Paths on data.study_id. An onboarding study files to the activation team, a billing study to the growth team.

Weekly digest instead of live tickets

For steady insight rather than urgent bugs, collect a week of matching interviews in Zapier's Digest and open one Linear issue with every summary and link. Engineering reads one ticket, not twenty.

Tie tickets back to accounts

Pass your own user or account ID as external_id when you start interviews through the API. It comes back in data.participant.external_id, so each ticket can name the account and your CRM can show the issue next to the customer.

The receiver approach (if you outgrow Zapier)

A small server, such as a serverless function, handles everything Zapier does and verifies the signature:

  1. Receive the POST and verify the webhook-id, webhook-timestamp and webhook-signature headers with your signing secret. Koji signs with the Standard Webhooks scheme, so any Standard Webhooks library does this in a few lines.
  2. Answer 2xx quickly, then do the work. Use webhook-id to ignore a message you have already handled, because retries resend the same ID.
  3. Apply your rules to data.trust.
  4. Fetch data.links.api with your API key.
  5. Build a Linear IssueCreateInput and call issueCreate on Linear's GraphQL API with a personal or OAuth key.

Polling the read endpoint on a schedule still works as a fallback, for example to backfill interviews from before you added the webhook.

Common pitfalls

  • Ticket floods. Start strict (quality 4 or higher and negative sentiment) and loosen later.
  • Expecting themes per interview. Themes come from the study report. Use the per-interview summary and key insights in tickets, and link the report when you discuss a theme.
  • Long titles. Linear titles should be short. Truncate the insight with a Zapier Formatter step.
  • Losing the evidence. Always include data.links.app, and the interview and study IDs, so the source can be found again.
  • Customer privacy. Summaries and transcripts can contain personal details. If participants are under NDA, keep transcripts in Koji and send only the summary and link. Turn on Remove personal details in the study and Koji takes names, emails and phone numbers out of each transcript before summaries are written.
  • Triage fatigue. Even with good filters, a busy research program can file several tickets a week. Rotate the triage role.

Why this changes how engineering teams ship

The biggest gain isn't the minutes saved on writing tickets. It's what gets prioritized. When every research ticket carries a summary of what the customer said and a link to the full interview, the planning conversation moves from "should we build this?" to "how do we fix what this customer hit?" Quality scores let you weigh the signal honestly, and anyone on the team can open the interview and judge it for themselves.

Related resources

Related Articles

Closing the Loop on Customer Feedback: The 2026 Playbook for Inner and Outer Loops

A complete guide to closing the customer feedback loop — inner loop vs outer loop, response-time benchmarks, automation playbooks, and how AI-native research turns 95% collected → 10% acted on into 100% closed.

Feature Request Management: A Modern Framework for Product Teams (2026)

How product teams capture, triage, and prioritize feature requests at scale — RICE, Kano, and value-vs-effort frameworks, voting vs interview signal, and how AI-native research separates real demand from loud asks.

How to Prioritize Customer Feedback: A Framework for Product Teams

A complete guide to triaging, scoring, and acting on customer feedback. Compare RICE, MoSCoW, Kano, and the Opportunity Solution Tree — and learn how AI-native research turns raw feedback into prioritized opportunities in minutes.

Sync Koji Customer Interviews to HubSpot: Live Insights on Every Contact

Push Koji interview transcripts, themes, and quality scores onto HubSpot contact and company records using the Koji API and the HubSpot API.

Jira + Koji: Auto-File Customer-Research-Backed Tickets and Close the Loop on Every Fix

Send Koji AI interview themes, customer quotes, and quality scores directly into Jira as fully-formed tickets — and pipe Jira ticket resolution back to the participants who reported it.

monday.com + Koji: Turn Board Automations into AI Customer Interviews

Connect monday.com to Koji to trigger AI voice and text interviews from board status changes and CRM pipeline stages, then sync themes and structured scores back into monday columns to close the feedback-to-roadmap loop.

Sync Koji Research Insights to Notion: Build a Self-Updating Research Repository

Connect Koji to Notion via Zapier (or the API) so every completed AI interview becomes a fresh Notion page — with transcript, structured answers, themes, quality score, and AI summary attached. Build a research repository that updates itself.

Productboard + Koji: Turn AI Interview Insights Into Roadmap Evidence Automatically

How to push grounded customer quotes from Koji AI interviews into Productboard as insights, so every roadmap item traces back to something a real customer said.

Research Automation: How to Build Real-Time Research Pipelines with Webhooks

Build automated research pipelines on Koji: event-triggered interviews, a signed webhook when each one is finished and scored, and insight routing to Slack, your CRM or a warehouse.

Research Handoff to Design and Engineering: What to Hand Over, in What Format, and How to Close the Loop

A stakeholder readout is not a handoff. Here is the exact packet design and engineering need from a research study — evidence-linked tickets, severity and confidence labels, edge cases, and the post-ship verification loop that proves the fix worked.

Send Research Insights to Slack: Real-Time Customer Interview Notifications via Webhooks

Get customer interview insights from Koji into Slack. There is no native Slack app, but Koji sends a signed interview.completed webhook from any study (Integrate, then Webhooks), which a small receiver or Zapier, Make or n8n turns into a Slack message seconds after each interview. Step-by-step setup with message recipes.

Structured Questions in AI Interviews

Mix quantitative data collection — scales, ratings, multiple choice, ranking — with AI-powered conversational follow-up in a single interview.

User Research API: Embed AI Interviews into Any Product or Workflow

How to use Koji's User Research API to run AI-moderated interviews from your own backend. Covers REST endpoints, the embed widget, signed completion webhooks, authentication, rate limits, and headless interview patterns.

Webhook Setup

Set up Koji webhooks: get a signed interview.completed message on your server each time a participant finishes, with your own participant ID and a quality score.

Connect Koji to Zapier: Automate Customer Research Workflows in Minutes

Route every completed AI customer interview from Koji into 6,000+ Zapier apps — including Notion, Linear, Salesforce, Airtable, and Gmail. A step-by-step integration guide.