{"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-06-07T15:12:29.608Z"},"content":[{"type":"documentation","id":"d795de05-22fb-4a0c-a666-eae3de9d075b","slug":"research-automation-webhooks","title":"Research Automation: How to Build Real-Time Research Pipelines with Webhooks","url":"https://www.koji.so/docs/research-automation-webhooks","summary":"Koji webhooks push interview and report data to any endpoint the moment an event occurs, enabling real-time Slack notifications, CRM sync, automated tagging, and fully automated research pipelines. Supported events: interview.completed, interview.failed_quality_gate, study.published, report.generated. Webhook payloads include participant attributes and structured question values. Configure in Settings > Webhooks. Use HMAC-SHA256 signature verification. Retries up to 3 times with exponential backoff.","content":"\n# Research Automation: How to Build Real-Time Research Pipelines with Webhooks\n\nA research pipeline is the infrastructure that moves data from your participants to the people who need to act on it — automatically. Traditional research workflows are manual: collect interviews, wait for analysis, write a report, share findings, repeat. This cycle takes days or weeks and produces insights that are stale by the time they reach decision-makers.\n\nKoji's webhook system enables a fundamentally different model: automated, real-time data flows that trigger actions the moment a participant completes an interview. Insights reach your team within seconds of being generated — not in the next sprint planning meeting.\n\n## How Webhooks Work\n\nA webhook is an HTTP POST request that Koji sends to a URL you specify when a specific event occurs. Unlike API polling — where you repeatedly check \"are there new interviews?\" — webhooks push data to you the instant something happens.\n\nThe basic flow:\n1. A participant completes a Koji interview\n2. Koji sends a POST request to your configured webhook URL with the event data\n3. Your system receives the data and triggers whatever action you have configured\n4. Everything happens automatically, typically within 2–5 seconds of completion\n\nYou configure webhooks in your workspace under **Settings → Webhooks**. Add your endpoint URL, select the events you want to subscribe to, and save.\n\n## Available Webhook Events\n\nKoji currently supports the following webhook events:\n\n**`interview.completed`**\nFired when a participant finishes an interview and it passes the [quality gate](/docs/how-the-quality-gate-works). Payload includes: interview ID, study ID, participant attributes (from personalized links), quality score, completion timestamp, and a direct link to view the transcript.\n\n**`interview.failed_quality_gate`**\nFired when an interview is completed but does not meet the minimum quality threshold. Useful for triggering follow-up outreach asking participants to try again, or for logging in your tracking system.\n\n**`study.published`**\nFired when you publish a study and make it live for participants. Useful for triggering team notifications or updating a research calendar in your project management tool.\n\n**`report.generated`**\nFired when a new report is generated or refreshed for a study. Payload includes key summary metrics and a link to the full report.\n\nEach event payload includes a `type` field, a `data` object with event-specific details, and a `timestamp` in ISO 8601 format.\n\n## Integration Patterns\n\n### Pattern 1: Real-Time Slack Notifications\n\nThe simplest webhook use case: notify your team when a new interview is completed.\n\nUsing a no-code tool like Zapier or Make, connect Koji's `interview.completed` event to a Slack channel. Your research team sees a notification like: \"New interview completed — Sarah (VP Engineering, Acme Corp, Enterprise plan). View transcript →\"\n\nFor time-sensitive studies — before a product launch, during a competitive analysis sprint, or when investigating a support escalation — real-time notifications mean you can act on an insight the same day it surfaces, not in the next planning cycle.\n\nSet up different Slack channels for different studies. Incoming signals from a churn research study route to your CS team's channel; signals from a feature validation study route to the product team.\n\n### Pattern 2: CRM Updates on Interview Completion\n\nFor sales, success, and marketing teams, interview completion can automatically update contact records.\n\n**Example: Post-trial interviews synced to Salesforce**\n\nWhen a trial user completes a Koji interview, a webhook triggers a Salesforce workflow that:\n- Marks the contact record as \"Research completed — date\"\n- Adds a note with the AI-generated interview summary\n- Assigns a follow-up task to the AE or CSM\n- Updates a custom satisfaction score field with the structured scale answer from the interview\n\nThis closes the loop between research and revenue-facing teams. The AE who calls a prospect to discuss renewal has context from a genuine qualitative conversation — not just CRM deal notes.\n\n**Example: Win/loss research synced to HubSpot**\n\nAfter a deal closes (won or lost), trigger a Koji interview via [personalized link](/docs/personalized-interview-links). When completed, the webhook updates the HubSpot deal record with competitive intelligence, pricing feedback, and decision factors extracted from the interview.\n\n### Pattern 3: Automated Research Tagging and Segmentation\n\nFor teams running ongoing research programs across multiple studies, webhooks automate participant tracking and segmentation.\n\nWhen an interview is completed:\n- Tag the participant in your CRM with the study topic and completion date\n- Update a custom attribute in your product analytics tool (Mixpanel, Amplitude, Heap) to mark users who have participated in research\n- Add the participant to a follow-up nurture sequence for future studies in the same theme area\n- Create a record in your research repository (Notion, Confluence, Airtable) with the interview metadata\n\nThis creates a complete research participation history for every user — automatically, without manual spreadsheet tracking.\n\n### Pattern 4: Automated Report Delivery\n\nWhen your Koji report is generated (`report.generated` event), automatically deliver it to stakeholders without any manual send:\n\n- **Slack**: Post a summary to a product or leadership channel with a link to the full report\n- **Email**: Trigger a personalized email via SendGrid or Mailchimp to each stakeholder with report highlights and the full link\n- **Notion or Confluence**: Create a new page in your research repository with the report content and metadata\n- **Linear or Jira**: Create action item tickets from the key recommendations surfaced in the report summary\n\nThis removes the \"send the report email\" step from your research workflow entirely — findings distribute themselves.\n\n### Pattern 5: End-to-End Automated Research Pipelines\n\nFor engineering teams, webhooks work in combination with Koji's [Headless API](/docs/headless-api-overview) to create fully automated research pipelines with no human intervention required:\n\n1. **Trigger event in your product**: User completes onboarding, trial expires, feature threshold reached, or NPS survey response received\n2. **Your backend calls Koji API**: Create a new interview session for that user, passing their context attributes (name, plan, feature usage)\n3. **User receives in-app or email prompt**: \"Take a 5-minute interview to help us improve — your feedback directly shapes the product\"\n4. **User completes interview**: Koji conducts the AI-moderated conversation\n5. **`interview.completed` webhook fires**: Your systems receive the structured data in real time\n6. **Downstream automation runs**: CRM updated, Slack notification sent, report refreshed, tickets created\n\nThis is research-as-infrastructure: qualitative insights flowing through your systems with the same reliability as any other data pipeline, 24 hours a day, without a researcher manually scheduling anything.\n\n## Setting Up Your First Webhook\n\n### Step 1: Create a Webhook Endpoint\n\n**Using a no-code tool:**\n- **Zapier**: Create a \"Webhooks by Zapier\" trigger and copy the generated URL\n- **Make**: Create an HTTP webhook module and copy the URL\n- **n8n**: Create an HTTP webhook trigger and copy the URL\n\n**Building a custom endpoint:**\n```javascript\n// Example: Express.js webhook handler\napp.post('/koji-webhook', express.raw({ type: 'application/json' }), (req, res) => {\n  const signature = req.headers['x-koji-signature'];\n  \n  if (!verifySignature(req.body, signature, process.env.KOJI_WEBHOOK_SECRET)) {\n    return res.status(401).send('Unauthorized');\n  }\n  \n  const event = JSON.parse(req.body);\n  \n  if (event.type === 'interview.completed') {\n    // Handle completed interview\n    console.log('Interview completed:', event.data.interview_id);\n  }\n  \n  res.status(200).send('OK');\n});\n```\n\nMake sure your endpoint returns a 200 status code within 10 seconds. Koji retries on timeout.\n\n### Step 2: Register the Webhook in Koji\n\n1. Navigate to **Settings → Webhooks** in your Koji workspace\n2. Click **Add Webhook**\n3. Enter your endpoint URL\n4. Select the events you want to subscribe to\n5. Save — Koji sends a test ping to verify the connection\n\n### Step 3: Understand the Payload Structure\n\nThe `interview.completed` payload:\n\n```json\n{\n  \"type\": \"interview.completed\",\n  \"timestamp\": \"2026-04-16T10:23:00Z\",\n  \"data\": {\n    \"interview_id\": \"abc123\",\n    \"study_id\": \"xyz789\",\n    \"study_title\": \"Post-Trial Feedback\",\n    \"participant\": {\n      \"name\": \"Sarah\",\n      \"company\": \"Acme Corp\",\n      \"email\": \"sarah@acme.com\",\n      \"plan\": \"enterprise\"\n    },\n    \"quality_score\": 4,\n    \"interaction_mode\": \"voice\",\n    \"completed_at\": \"2026-04-16T10:22:55Z\",\n    \"transcript_url\": \"https://app.koji.so/studies/xyz789/interviews/abc123\"\n  }\n}\n```\n\nWhen your study includes structured questions, the payload also includes `structured_answers` — an array of question IDs, types, and extracted values. This means a satisfaction scale rating or a single-choice response is available in your webhook payload in real time, without waiting for a full report refresh.\n\n### Step 4: Verify Webhook Signatures\n\nKoji signs all webhook payloads using HMAC-SHA256. The signature appears in the `X-Koji-Signature` header. Always verify this in your handler:\n\n```javascript\nconst crypto = require('crypto');\n\nfunction verifySignature(payload, signature, secret) {\n  const expected = crypto\n    .createHmac('sha256', secret)\n    .update(payload)\n    .digest('hex');\n  return crypto.timingSafeEqual(\n    Buffer.from('sha256=' + expected),\n    Buffer.from(signature)\n  );\n}\n```\n\nYour webhook secret is available in **Settings → Webhooks** after registering your endpoint.\n\n### Step 5: Handle Retries and Deduplication\n\nKoji retries failed webhook deliveries up to 3 times with exponential backoff (approximately 30 seconds, 5 minutes, and 30 minutes after the initial failure). To prevent duplicate processing:\n\n- Store processed `interview_id` values in your database\n- Before processing any webhook, check whether that ID has already been handled\n- Return 200 immediately even if you are processing asynchronously — this prevents Koji from treating slow processing as a failure\n\n## Structured Questions + Webhooks: Real-Time Quantitative Signals\n\nStudies using [structured questions](/docs/structured-questions-guide) produce richer webhook payloads. Koji supports six question types: open_ended, scale, single_choice, multiple_choice, ranking, and yes_no. Structured question values are included in the `interview.completed` payload as `structured_answers`.\n\nThis enables powerful routing logic:\n- **Low satisfaction score** (scale question, score 1–5): create a CS follow-up task immediately\n- **Negative expansion intent** (yes_no question, answer \"no\"): flag the account in Salesforce for at-risk review\n- **Specific churn reason selected** (single_choice question, option \"pricing\"): route to a pricing-focused win-back sequence\n\nQuantitative structured data flowing through webhooks in real time is one of the most powerful features of Koji's platform — transforming qualitative research into an operational data source your entire revenue stack can act on.\n\n## Monitoring and Debugging\n\nIn **Settings → Webhooks**, you can view delivery history for each registered endpoint:\n- Status of each delivery attempt (success or failure)\n- HTTP response code returned by your endpoint\n- Payload content for debugging\n- Option to manually retry failed deliveries\n\nIf you are developing locally, use a tool like ngrok to expose a local endpoint for testing before deploying to production.\n\n## Related Resources\n\n- [Structured Questions Guide](/docs/structured-questions-guide) — Add quantitative data to webhook payloads for real-time routing logic\n- [Webhook Setup](/docs/webhook-setup) — Quick-start configuration guide\n- [Headless API Overview](/docs/headless-api-overview) — Full API access for building automated research pipelines\n- [API Authentication](/docs/api-authentication) — Secure your API and webhook integrations\n- [Personalized Interview Links](/docs/personalized-interview-links) — Embed participant context that appears in webhook payloads\n- [Rate Limits and CORS](/docs/rate-limits-and-cors) — API constraints to plan around when building integrations\n\n\n## Further reading on the blog\n\n- [How to Build a UX Research Portfolio That Gets You Hired in 2026](/blog/ux-research-portfolio-guide-2026) — The 2026 playbook for building a UX research portfolio that gets you hired — what to include, what to skip, and how to demonstrate AI fluenc\n- [Agile User Research: How to Run Continuous Research in Sprint Cycles (2026)](/blog/agile-user-research-2026) — Most teams know they should do user research every sprint. Almost none actually do. Here's the practical playbook for integrating continuous\n- [AI Agents for User Research in 2026: How Autonomous Research Is Reshaping Customer Insight](/blog/ai-agents-user-research-2026) — AI agents are taking over user research in 2026 — moderating interviews, synthesizing themes, and producing insight reports in hours. The fu\n\n<!-- further-reading:blog -->\n","category":"API Reference","lastModified":"2026-05-31T03:27:37.096681+00:00","metaTitle":"Research Automation with Webhooks | Koji Docs","metaDescription":"Build real-time research pipelines with Koji webhooks. Trigger Slack alerts, CRM updates, and automated workflows the moment an interview is completed. Includes payload examples, signature verification, and end-to-end pipeline patterns.","keywords":["research automation webhooks","user research webhook","automated research pipeline","real-time research data","research webhook integration","continuous research automation","qualitative data webhook"],"aiSummary":"Koji webhooks push interview and report data to any endpoint the moment an event occurs, enabling real-time Slack notifications, CRM sync, automated tagging, and fully automated research pipelines. Supported events: interview.completed, interview.failed_quality_gate, study.published, report.generated. Webhook payloads include participant attributes and structured question values. Configure in Settings > Webhooks. Use HMAC-SHA256 signature verification. Retries up to 3 times with exponential backoff.","aiPrerequisites":["Familiarity with HTTP and REST APIs","Koji account on Interviews plan or higher for webhooks","A webhook endpoint (can use Zapier or Make for no-code setup)"],"aiLearningOutcomes":["Configure webhook endpoints in Koji settings","Handle interview.completed events with participant data","Build Slack notification workflows for real-time research alerts","Sync interview completions to CRM records automatically","Create end-to-end automated research pipelines with the Headless API","Verify webhook signatures for security"],"aiDifficulty":"intermediate","aiEstimatedTime":"15 minutes"}],"pagination":{"total":1,"returned":1,"offset":0}}