Webhooks

Webhook-Events

Daneben gibt es zwei Service-Events: endpoint.verification (wird beim Anlegen und bei einer URL-Änderung gesendet; antworten Sie mit 2xx, um den Endpunkt zu aktivieren) und endpoint.test (wird gesendet, wenn Sie in der Konsole „Test senden“ auslösen oder die Test-API aufrufen).

Request-Body

Eine Webhook-Anfrage enthält Kennungen und Verarbeitungsstatus, aber weder Transkript noch Zusammenfassung. Rufen Sie nach der Benachrichtigung den aktuellen Inhalt mit der note_id über die REST API ab.

{
  "event_id": "5f8c0a5e-...",
  "event_type": "note.ended",
  "occurred_at": "2026-08-12T05:20:00Z",
  "data": {
    "note_id": "note_abc123",
    "recording_session_id": "rec_456",
    "revision": 7,
    "transcript_status": "ready",
    "summary_status": "pending"
  }
}

Signaturen prüfen

Alt signiert jede Anfrage mit dem beim Anlegen des Endpunkts ausgestellten Secret (whsec_...). Das Signaturformat folgt der Spezifikation von Standard Webhooks:

POST /webhooks/alt HTTP/1.1
Content-Type: application/json
webhook-id: 5f8c0a5e-...
webhook-timestamp: 1765515600
webhook-signature: v1,K5oZfzN95Z9UVu1EsPQmSmZQGGVfCM0jaZ0lPI4dvLU=

signed_content = "{webhook-id}.{webhook-timestamp}.{raw request body}"
signature     = base64( HMAC-SHA256( base64url_decode(secret_after_whsec_), signed_content ) )

• Prüfen Sie die Signatur anhand des rohen Request-Bodys, bevor Ihr Framework das JSON verarbeitet. Ein erneutes Serialisieren kann den Body verändern und die Prüfung fehlschlagen lassen.
• Vergleichen Sie Signaturen mit einem Vergleich in konstanter Laufzeit (constant-time).
• Weisen Sie veraltete Timestamps zurück (wir empfehlen eine Toleranz von ±5 Minuten), um Replay-Angriffe zu verhindern.
• Weisen Sie Requests mit nicht passender Signatur mit 4xx zurück. Lauffähiger Empfänger-Code: Quickstart, Schritt 4.

Zustellfehler und Retries

• Antworten Sie innerhalb von 10 Sekunden mit 2xx. Andere Statuscodes oder ein Timeout gelten als Zustellfehler. Antworten Sie zuerst und verarbeiten Sie das Event anschließend asynchron.
• Fehlgeschlagene Zustellungen werden mit wachsendem Backoff wiederholt (30 s → 5 min → 30 min → 2 h → 12 h → 12 h, insgesamt bis zu 7 Versuche).
• Ein Endpunkt, bei dem viele Zustellungen in Folge fehlschlagen, wird automatisch deaktiviert.
• Redirects werden nicht verfolgt; die Webhook-URL muss direkt über HTTPS antworten.

Doppelte Events behandeln

Webhooks werden nach dem Prinzip at-least-once zugestellt. Durch Retries oder erneutes Senden aus der Konsole kann dasselbe Event mehrfach eintreffen. Speichern Sie verarbeitete event_ids vorübergehend und überspringen Sie bereits behandelte Events.

Vertauschte Event-Reihenfolgen behandeln

Retries und parallele Zustellungen können dazu führen, dass Events in einer anderen Reihenfolge eintreffen als sie entstanden sind. Das zuletzt empfangene Event enthält daher nicht unbedingt den neuesten Stand. Bei jeder API-sichtbaren Änderung erhöht der Server die revision der Notiz. Speichern Sie pro Notiz die zuletzt angewendete Revision und ignorieren Sie gleiche oder kleinere Werte. Ist die Reihenfolge unklar, rufen Sie die Notiz erneut über die REST API ab; sie liefert immer die aktuelle Revision.

Auf verpasste Änderungen prüfen

• Webhooks können fehlen, wenn Ihr Empfänger länger als das Retry-Fenster nicht erreichbar oder der Endpunkt deaktiviert ist. Rufen Sie regelmäßig GET /v1/notes?updated_after=<last sync> auf, um Änderungen seit der letzten Synchronisierung nachzuladen.
• note.deleted mit reason: "access_lost" bedeutet, dass die Notiz den Bereich Ihrer Zugangsdaten verlassen hat (z. B. weil eine persönliche Notiz in einen Teamspace verschoben wurde). Behandeln Sie das genau wie eine Löschung: Entfernen Sie Ihre gespeicherte Kopie oder sperren Sie den Zugriff darauf.
• Eine inkrementelle Abfrage allein erkennt weder Löschungen noch verlorenen Zugriff. Rufen Sie deshalb regelmäßig auch die vollständige Notizliste ab. Mit include_deleted=true enthält sie Löschmarker (Tombstones). Fehlt eine gespeicherte Notiz-ID in der vollständigen Liste, wurde sie gelöscht oder hat Ihren Zugriffsbereich verlassen.