Webhooks einrichten

Voraussetzungen

• knowmind-Konto, in jedem Tarif
• Eine per HTTPS erreichbare Adresse unter Ihrer Kontrolle, zum Beispiel eine eigene Anwendung oder ein Webhook-Knoten in n8n
• Ein sicherer Ablageort für das Geheimnis, mit dem Sie die Signatur prüfen

Schritte

1. 1

   Webhook im Cockpit anlegen

   Öffnen Sie im Cockpit Webhooks und legen Sie einen Webhook an: Adresse eintragen (HTTPS ist Pflicht), Ereignisse auswählen, speichern.

   Ergebnis: knowmind zeigt das Geheimnis für die Signatur einmal an. Kopieren Sie es sofort und legen Sie es sicher ab; später lässt es sich nicht mehr abrufen.

2. 2

   Testmeldung auslösen

   Klicken Sie in der Liste der Webhooks auf den Test-Knopf neben dem neuen Eintrag. knowmind sendet eine Meldung vom Typ webhook.test.

   Ergebnis: Im Protokoll Ihrer Adresse erscheint die Testanfrage.

3. 3

   Signatur prüfen

   Jeder Webhook enthält im Header X-knowmind-Signature den Wert sha256=<hex>. Das ist der HMAC-SHA256 über den unveränderten Inhalt der Anfrage, gerechnet mit Ihrem Geheimnis. Prüfen Sie die Signatur, bevor Sie den Inhalt verarbeiten: Ohne Prüfung kann jeder gefälschte Meldungen an Ihre Adresse schicken.

   tskopieren

   // Node.js / Next.js Beispiel
   import { createHmac, timingSafeEqual } from "node:crypto";
   
   export function verifyKnowmindSignature(
     body: string,
     header: string,
     secret: string,
   ): boolean {
     const mac = createHmac("sha256", secret).update(body).digest("hex");
     const expected = "sha256=" + mac;
     if (header.length !== expected.length) return false;
     return timingSafeEqual(Buffer.from(header), Buffer.from(expected));
   }

   pythonkopieren

   import hmac, hashlib
   
   def verify_knowmind_signature(body: bytes, header: str, secret: str) -> bool:
       mac = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
       expected = "sha256=" + mac
       return hmac.compare_digest(header, expected)

4. 4

   Wiederholungen einplanen

   knowmind erwartet innerhalb von 15 Sekunden eine Antwort mit einem Status 2xx. Bleibt sie aus oder kommt ein Fehler zurück, wiederholt knowmind die Zustellung in wachsenden Abständen: sofort, nach 1 Minute, 5 Minuten, 30 Minuten, 2 Stunden und 12 Stunden. Nach sechs erfolglosen Versuchen gilt die Meldung als nicht zustellbar. Nach 20 Fehlern in Folge schaltet knowmind den Webhook ab; im Cockpit schalten Sie ihn wieder ein.

   Antworten Sie deshalb sofort mit 2xx und verarbeiten Sie die Meldung danach. Der Header X-knowmind-Delivery ist je Meldung eindeutig: Merken Sie sich seinen Wert, dann verarbeiten Sie eine wiederholte Meldung nicht doppelt.

Ereignisse

Aufbau einer Meldung

Jede Meldung ist ein POST mit JSON-Inhalt und festen Headern. Sie enthält Kennungen, Zeitpunkt und Ereignistyp. Den vollen Text einer Erinnerung holen Sie bei Bedarf über die Schnittstelle nach.

POST /ihr-empfaenger HTTP/1.1
Content-Type: application/json
X-knowmind-Event: memory.created
X-knowmind-Delivery: 8b1f4f2e-3c4d-4e5a-9c2b-7f8e9d0a1b2c
X-knowmind-Signature: sha256=2a8f3b…

{
  "event": "memory.created",
  "tenantId": "00000000-0000-0000-0000-0000000050c1",
  "occurredAt": "2026-05-22T15:42:11.123Z",
  "data": {
    "documentId": "ab72ddfc-5f50-46d9-90d1-5849c96e01c0",
    "title": "Quartalsmeeting Müller",
    "chunksWritten": 4
  }
}

Prüfung des Ergebnisses

Fehlerbehebung