Webhook Setup

Let's be direct up front: Koji does not have native outbound webhooks yet. There is no place to register a webhook URL, no signing secret, and no webhook event payloads. Native webhooks are on the roadmap. Until they ship, this guide covers the three patterns that get you the same outcome today, reliably.

---

What you can build today

---

Option 1: Poll the read endpoint

The read endpoint returns the interview's status, transcript, stats, and (once ready) the AI analysis:

curl https://www.koji.so/api/v1/interviews/9f4c1e2a-7b3d-4e8f-a1c5-2d6b8e0f4a7c \
  -H "Authorization: Bearer pk_live_wJalrXUtnFEMI4K7MDENGbPxRfiCYz2K"

Returns the full transcript, respondent info, stats, and (once ready) the AI analysis. Server-to-server friendly. No session token required.

The full loop has four steps:

1. When you call POST /interviews/start, store the returned interview_id (plus your own external_id) in a pending table.
2. A scheduled job fetches each pending id every minute.
3. When status is completed and analysis is present, run your handler and remove the id from the table.
4. Expire ids after a reasonable window so the poller does not grow unbounded.

Step 2 and 3 in code:

// Runs on your server every minute (cron job, worker, or scheduled function).
// pendingIds holds interview ids you stored when you called the start endpoint.
const API_KEY = 'pk_live_wJalrXUtnFEMI4K7MDENGbPxRfiCYz2K'

async function checkPending(pendingIds) {
  for (const id of pendingIds) {
    const res = await fetch(`https://www.koji.so/api/v1/interviews/${id}`, {
      headers: { 'Authorization': `Bearer ${API_KEY}` },
    })
    if (!res.ok) continue

    const interview = await res.json()
    if (interview.status === 'completed' && interview.analysis) {
      await handleCompleted(interview) // your "webhook handler"
      // Remove id from your pending store so it is not processed twice
    }
  }
}

Two details make this robust:

• analysis is populated only after the interview is completed and the background analysis has finished; otherwise it is null. Waiting for status === 'completed' && analysis gives you the fully processed result in one pass.
• The key needs the interview:read permission and no session token, so a single server-side key covers the whole worker. See API Key Permissions.

Mind your rate limit: each key allows 60 requests per minute by default, so a poller checking large batches should spread requests or batch by minute. See Rate Limits and CORS.

---

Option 2: Forward the embed completed event

If your interviews run in the embed widget, the browser already knows the moment an interview finishes. The widget posts this event to the parent page:

{
  "type": "koji:interview_completed",
  "conversationId": "9f4c1e2a-7b3d-4e8f-a1c5-2d6b8e0f4a7c",
  "messageCount": 18
}

The interview finishes (AI-detected or respondent-driven). Does not re-fire when a completed interview is reloaded. Forward it to your backend and you have a webhook-shaped signal:

window.addEventListener('message', (event) => {
  // Always verify the sender before trusting the payload
  if (event.origin !== 'https://www.koji.so') return
  if (event.data?.type !== 'koji:interview_completed') return

  // Forward the completion signal to your own backend
  fetch('/api/koji/interview-completed', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(event.data),
  })
})

Treat this as a fast path, not the source of truth: it only fires while the respondent's tab is open, and it does not re-fire if a completed interview is reloaded. Pair it with Option 1 polling for interviews whose event never arrived. Full event reference in Embed Widget Reference.

---

Option 3: Automation platforms

Zapier, n8n, and Make can all drive the REST API on a schedule with their generic HTTP modules:

1. A schedule trigger runs every few minutes.
2. An HTTP step calls GET https://www.koji.so/api/v1/interviews/{id} for each pending id with your Authorization: Bearer header.
3. A filter passes only interviews where status is completed and analysis is present.
4. Downstream steps route the result: Slack message, CRM update, spreadsheet row.

This is Option 1 without writing code. The same rate limit and permission notes apply.

---

Native webhooks: coming soon

Outbound webhooks are planned. When they ship, they will replace the polling loop, not the rest of your pipeline: keep your completion handling in one function (like handleCompleted above) and the switch will be a one-line change from poller to webhook receiver.

---

FAQ

Where do I register my webhook URL?

Nowhere yet. Koji has no native outbound webhooks today. Use one of the three patterns above.

How often should I poll?

Every minute is a good default. With the default limit of 60 requests per minute per key, that is up to 60 pending interviews checked per cycle without special handling.

Is the embed event enough on its own?

No. It only fires in an open browser tab and never re-fires for already-completed interviews. Use it for instant UX reactions and keep polling as the source of truth.

Will I need to rebuild when native webhooks ship?

Not if you isolate completion handling in one function. Swap the trigger from your poller to the webhook receiver and keep everything downstream unchanged.

Does polling give me the transcript too, or just the analysis?

Everything. The read endpoint returns the full transcript, respondent info (including your external_id), session stats, and the analysis in a single response, so one fetch feeds every downstream destination.