{"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-11-18T05:53:50.168Z"},"content":[{"type":"documentation","id":"1b16f433-4237-4eea-9496-b53a09b88482","slug":"linear-research-integration","title":"Send Koji Insights to Linear: Auto-File Engineering Tickets from Customer Interviews","url":"https://www.koji.so/docs/linear-research-integration","summary":"Connect Koji to Linear so interviews that surface real customer problems open Linear issues automatically. Every Koji study can send a signed interview.completed webhook (Integrate, then Webhooks) when an interview is finished and scored. The message carries the study, mode, your external participant ID, a trust block with the quality score, quality level, quality bar and fraud risk, and links to the interview. A Zapier catch hook or a small receiver filters on that trust block, fetches the AI summary, key insights and sentiment from the read endpoint with a study API key, and calls Linear to create the issue. The guide covers which interviews should become tickets, the Zapier setup, deduplication, routing by study, weekly digests and a signature-checking receiver for teams that outgrow Zapier. Webhooks are on Insights, Interviews and Enterprise; API keys come with Interviews and Enterprise.","content":"**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.\n\n## Why teams sync Koji to Linear\n\nLinear 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.\n\nThe 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.\n\nA 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:\n\n- Koji's AI summary of the interview\n- The key insights, as a list\n- The overall sentiment (positive, negative or mixed)\n- The quality score and level, so engineering can weigh the signal\n- The study name and interview mode (text, voice or phone)\n- A direct link to the interview in Koji, where anyone on the team can read the transcript\n\n## What Koji sends, and what you fetch\n\nTwo pieces of the Koji API do the work. Knowing which field lives where saves most of the debugging.\n\n**The webhook** (`interview.completed`) arrives when an interview is finished and scored. It is small on purpose:\n\n| Field | What it holds |\n|---|---|\n| `data.interview_id`, `data.study_id`, `data.study_name` | Which interview and study |\n| `data.mode` | `text`, `voice` or `phone` |\n| `data.participant.external_id` | Your own ID for the person, if you passed one in (null for panel participants) |\n| `data.trust.quality_score` | The interview's quality score, 1 to 5 |\n| `data.trust.quality_level` | Shallow, Fair, Good or Excellent |\n| `data.trust.meets_quality_bar` | True when the interview counts towards the report |\n| `data.trust.fraud_risk` | high, medium, low or unknown |\n| `data.links.app` | The interview in Koji |\n| `data.links.api` | The read endpoint for this interview |\n\n**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.\n\nThe 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.\n\n## Integration paths\n\n1. **Zapier (recommended):** point and click, about 20 minutes, no code\n2. **Your own receiver plus Linear's GraphQL API (advanced):** verify the signature yourself, then call Linear directly\n\nStart with Zapier. Build your own receiver once you need signature checks, richer formatting or high volume.\n\n## Prerequisites\n\n- A Koji study with at least one completed interview\n- 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.\n- A Linear workspace where you can create issues in at least one team\n- A Zapier account on a plan that includes webhooks and filters\n- About 20 minutes\n\n## Step 1: Decide which interviews become tickets\n\nThis 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.\n\nRules that work:\n\n- **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.\n- **Drop risky sessions.** Skip anything with `fraud_risk` set to `high`.\n- **Negative sentiment.** After fetching the analysis, continue only when `analysis.sentiment` is `negative` or `mixed`. Happy interviews rarely need a ticket.\n- **Keywords in the insights.** Continue only when a key insight mentions words your team cares about (\"bug\", \"slow\", \"can't\", \"missing\", \"error\").\n- **Combine them.** \"Quality 4 or higher AND sentiment negative\" is a good default.\n\nWrite the rule down before you build. You can change it later, but a default stops the first-day flood.\n\n## Step 2: Add the webhook in Koji\n\nIn Koji, open the study, then **Integrate**, then **Webhooks**:\n\n1. Paste the Zapier hook URL from Step 3 as the endpoint URL (create the Zap first, or come back to this step)\n2. Subscribe to `interview.completed`\n3. Choose this study, or every study including new ones\n4. Copy the signing secret somewhere safe\n5. Send a test event and check the delivery log shows a 2xx answer\n\n![Process showing six steps to set up a Koji webhook, from opening Integrate to sending a test event and watching the delivery log.](/visuals/koji-webhook-setup-steps/koji-webhook-setup-steps.png \"The same six steps work for any destination, Linear included\")\n\nEvery 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](/docs/webhook-setup).\n\nAlso create a study API key (see [API authentication](/docs/api-authentication)). Zapier uses it to fetch the analysis.\n\n## Step 3: Create the Zap\n\nIn Zapier:\n\n1. 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.\n2. 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`.\n3. Add **Webhooks by Zapier: GET** to the URL in `data.links.api`, with the header `Authorization: Bearer <your study API key>`.\n4. Add a second filter on the GET result, for example `analysis.sentiment` is `negative` or `mixed`.\n\nZapier'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.\n\n## Step 4: Create the Linear issue\n\nAdd **Linear: Create Issue** and connect your workspace. Configure:\n\n- **Team:** the team that owns this part of the product\n- **Title:** `[Research] {data.study_name}: {first item of analysis.key_insights}`. Truncate to keep it short.\n- **Description** (Linear supports markdown):\n\n```\n**Summary:** {analysis.summary}\n\n**Key insights:**\n{analysis.key_insights, one per line}\n\n**Sentiment:** {analysis.sentiment}\n**Quality:** {data.trust.quality_level} ({data.trust.quality_score}/5)\n**Study:** {data.study_name} ({data.mode} interview)\n**Customer ID:** {data.participant.external_id}\n\n**Read the interview in Koji:** {data.links.app}\n\n---\nFiled from Koji. Edit or close if not actionable.\n```\n\n- **Labels:** a fixed `research` label, plus one per study or product area if you route by study\n- **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`.\n- **Assignee:** empty, so triage picks it up\n\nSend a test through the whole Zap. The issue should land in the team's triage within seconds.\n\n## Step 5: Turn it on and tune\n\nSwitch 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.\n\n## Patterns that pay off\n\n### One issue per problem, not per interview\n\nAdd 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.\n\n### Route by study\n\nPoint 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.\n\n### Weekly digest instead of live tickets\n\nFor 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.\n\n### Tie tickets back to accounts\n\nPass 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.\n\n## The receiver approach (if you outgrow Zapier)\n\nA small server, such as a serverless function, handles everything Zapier does and verifies the signature:\n\n1. 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.\n2. Answer 2xx quickly, then do the work. Use `webhook-id` to ignore a message you have already handled, because retries resend the same ID.\n3. Apply your rules to `data.trust`.\n4. Fetch `data.links.api` with your API key.\n5. Build a Linear `IssueCreateInput` and call `issueCreate` on Linear's GraphQL API with a personal or OAuth key.\n\nPolling the read endpoint on a schedule still works as a fallback, for example to backfill interviews from before you added the webhook.\n\n## Common pitfalls\n\n- **Ticket floods.** Start strict (quality 4 or higher and negative sentiment) and loosen later.\n- **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.\n- **Long titles.** Linear titles should be short. Truncate the insight with a Zapier Formatter step.\n- **Losing the evidence.** Always include `data.links.app`, and the interview and study IDs, so the source can be found again.\n- **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.\n- **Triage fatigue.** Even with good filters, a busy research program can file several tickets a week. Rotate the triage role.\n\n## Why this changes how engineering teams ship\n\nThe 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.\n\n## Related resources\n\n- [Webhook Setup](/docs/webhook-setup): the webhook reference, signatures and the delivery log\n- [Research Automation with Webhooks](/docs/research-automation-webhooks): more pipelines built on interview.completed\n- [Connect Koji to Zapier](/docs/zapier-research-automation): the foundational Zapier guide\n- [Sync Koji Insights to Productboard](/docs/productboard-research-integration): turn interview evidence into roadmap evidence\n- [Send Research Insights to Slack](/docs/slack-research-insights-integration): post summaries and report links to Slack\n- [Koji Structured Questions Guide](/docs/structured-questions-guide): the question types you can combine in one interview\n- [User Research API](/docs/user-research-api-guide): the full API reference for direct integration\n","category":"API Reference","lastModified":"2026-11-17T05:15:14.98789+00:00","metaTitle":"Sync Koji to Linear: Auto-File Tickets from Customer Interviews","metaDescription":"Connect Koji to Linear with the signed interview.completed webhook and Zapier or Linear's GraphQL API. Filter on quality and sentiment, attach the AI summary and a link to the interview.","keywords":["koji linear integration","linear customer feedback","auto-create linear tickets","customer interview to linear","research linear automation","linear webhook research","koji zapier linear","product feedback linear"],"aiSummary":"Connect Koji to Linear so interviews that surface real customer problems open Linear issues automatically. Every Koji study can send a signed interview.completed webhook (Integrate, then Webhooks) when an interview is finished and scored. The message carries the study, mode, your external participant ID, a trust block with the quality score, quality level, quality bar and fraud risk, and links to the interview. A Zapier catch hook or a small receiver filters on that trust block, fetches the AI summary, key insights and sentiment from the read endpoint with a study API key, and calls Linear to create the issue. The guide covers which interviews should become tickets, the Zapier setup, deduplication, routing by study, weekly digests and a signature-checking receiver for teams that outgrow Zapier. Webhooks are on Insights, Interviews and Enterprise; API keys come with Interviews and Enterprise.","aiPrerequisites":["A Koji study with at least one completed interview","A Linear workspace with issue-creation permission","A Zapier account (Starter plan recommended for filters)","About 20 minutes"],"aiLearningOutcomes":["Choose the right filter rules so your Linear backlog doesn't explode","Set up a Zapier schedule that polls Koji for completed interviews","Build a Linear issue description that includes verbatim quotes and metadata","Map quality scores to Linear priority automatically","Route different themes to different Linear teams","Deduplicate issues using Linear's Find Issue lookup","Migrate to direct Linear GraphQL API when volume justifies it","Anonymize quotes for privacy-sensitive participants"],"aiDifficulty":"intermediate","aiEstimatedTime":"12 min read"}],"pagination":{"total":1,"returned":1,"offset":0}}