Webhooks

Webhooks schicken Ihrem Server ein JSON-Ereignis, sobald Kuno einen Verarbeitungsschritt abgeschlossen hat. Jede Zustellung ist mit einem endpunkt-eigenen Geheimnis signiert, damit Ihr Server prüfen kann, dass sie wirklich von Kuno stammt.

Endpunkt registrieren

1. Webhook anlegen. In der App: Einstellungen → Entwickler-Einstellungen → Webhooks → „Webhook hinzufügen". HTTPS-Payload-URL eingeben und Ereignisse wählen (bis zu 10 Endpunkte pro Konto).
2. Signatur-Geheimnis sichern. Das Geheimnis (kuno_whsec_…) wird genau einmal angezeigt — beim Endpunkt hinterlegen.
3. Testereignis senden. In der Detailansicht ein Testereignis auslösen — Kuno zeigt direkt den HTTP-Status Ihrer Antwort.

In der Detailansicht können Sie den Endpunkt außerdem pausieren und fortsetzen, das Geheimnis rotieren, die letzten Zustellungen einsehen oder den Webhook löschen.

Ereignisse

Typ	Wird ausgelöst, wenn …	Payload-Highlights
transcription.completed	ein Transkript fertig ist.	data.transcript.segments — Sprecher, Text, Zeiten.
summary.completed	eine Zusammenfassung fertig ist.	data.summary — Titel, Text, Kernpunkte, Entscheidungen, Aufgaben.
recording.processed	die gesamte Verarbeitung erfolgreich abgeschlossen ist.	nur data.recording — ein leichtes „fertig"-Signal.
ping	Sie in der App ein Testereignis senden.	data.webhookId.

Jedes Ereignis enthält zusätzlich data.recording mit ID, Titel, Status, Dauer und Sprache der Notiz.

Envelope

{
  "id": "evt_5f0c4c8e-…",
  "type": "summary.completed",
  "createdAt": "2026-07-04T08:12:31.000Z",
  "data": {
    "recording": { "id": "…", "title": "Standup-Notizen", "status": "processed",
                   "durationSeconds": 1260, "languageCode": "de" },
    "summary": { "id": "…", "title": "Standup — 4. Juli", "body": "…",
                 "keyPoints": ["…"], "decisions": ["…"],
                 "actionItems": ["…"] }
  }
}

Zustellungs-Header

Header	Wert
X-Kuno-Event	Der Ereignistyp.
X-Kuno-Event-Id	Die Envelope-id — hierauf deduplizieren.
X-Kuno-Timestamp	Unix-Sekunden zum Signaturzeitpunkt.
X-Kuno-Signature	v1=<hex HMAC-SHA256>
User-Agent	Kuno-Webhooks/1.0

Signatur prüfen

Signiert wird die Zeichenkette {timestamp}.{rawBody} — die rohen Request-Bytes, kein neu serialisiertes JSON. Vergleichen Sie in konstanter Zeit und lehnen Sie Zeitstempel ab, die älter als ~5 Minuten sind:

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(secret, timestamp, rawBody, signatureHeader) {
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected =
    "v1=" +
    createHmac("sha256", secret)
      .update(`${timestamp}.${rawBody}`)
      .digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(signatureHeader);
  return a.length === b.length && timingSafeEqual(a, b);
}

Zustellung & Wiederholungen

• HTTP-POST mit JSON-Body; antworten Sie innerhalb von 10 Sekunden mit einem 2xx.
• Fehlgeschlagene Zustellungen werden zweimal wiederholt (nach ca. 2 s und 10 s) — drei Versuche insgesamt. Zustellung ist at-least-once: deduplizieren Sie über X-Kuno-Event-Id.
• Nach 20 aufeinanderfolgenden Fehlern wird der Endpunkt automatisch pausiert; die App zeigt den Grund, und Sie können ihn nach der Reparatur Ihres Servers wieder aktivieren.
• Testereignisse zählen mit: Ein manuell gesendetes Testereignis läuft über denselben Fehlerzähler wie echte Zustellungen. Ein fehlgeschlagener Test bringt den Endpunkt also näher an die automatische Pause, und ein erfolgreicher Test setzt den Zähler auf null zurück — das kann ein instabiles Setup verschleiern, wenn Sie nur gelegentlich testen.

Sicherheit: Endpunkte müssen öffentliche HTTPS-URLs sein — private und interne Hosts werden abgelehnt. Nach einer Geheimnis-Rotation wird sofort neu signiert: aktualisieren Sie zuerst Ihren Server. Webhook-Payloads enthalten Ihre Notiz-Inhalte — behandeln Sie Ihren Endpunkt wie jedes System mit personenbezogenen Daten.