Integration

Webhooks

knowmind schickt HTTP-POSTs an Ihre URL, sobald in Ihrem Arbeitsbereich etwas Relevantes passiert — eine neue Erinnerung angelegt, eine Beziehung gezogen, ein Tarif gewechselt. Verfügbar ab dem Team-Tarif.

Einrichtung in vier Schritten

1. Dashboard → Webhooks → „Webhook anlegen".
2. URL eintragen (HTTPS Pflicht), Events auswählen, Anlegen klicken.
3. knowmind zeigt Ihnen einmalig das Secret — kopieren, sicher aufbewahren. Damit verifizieren Sie die HMAC-Signatur jedes eingehenden Webhooks.
4. Über „Test"-Button im Dashboard ein synthetisches Event auslösen, um die Strecke zu prüfen.

Event-Typen

Payload-Format

Jede Lieferung ist ein POST mit JSON-Body und festen Headern:

POST /your-webhook-handler HTTP/1.1
Content-Type: application/json
User-Agent: knowmind-Webhook/1.0
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
  }
}

Signatur prüfen

Header X-knowmind-Signature enthält sha256=<hex> — das ist HMAC-SHA256 des unveränderten Roh-Bodys mit Ihrem Secret als Schlüssel. Wenn die Signatur nicht passt, gehört der Request nicht zu Ihnen — verwerfen.

// 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));
}

# Python Beispiel
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)

Retry-Strategie

Antwort 2xx innerhalb von 15 Sekunden = Erfolg. Alles andere (Timeout, 4xx, 5xx, Transportfehler) löst einen Retry aus. Exponential Backoff:

• 1. Versuch: sofort
• 2. Versuch: nach 1 Minute
• 3. Versuch: nach 5 Minuten
• 4. Versuch: nach 30 Minuten
• 5. Versuch: nach 2 Stunden
• 6. Versuch: nach 12 Stunden

Nach 6 erfolglosen Versuchen wird die Lieferung als dead markiert. Nach 20 aufeinanderfolgenden Fehlern wird die gesamte Subscription automatisch deaktiviert — sichtbar im Dashboard, manuell reaktivierbar.

Best Practices

• Sofort 200 antworten, dann die Verarbeitung in eine Queue schieben — sonst riskieren Sie Timeouts.
• Idempotent verarbeiten: Bei Retry kann derselbe Event erneut ankommen. Nutzen Sie X-knowmind-Delivery als Idempotenz-Key.
• Signatur immer prüfen. Ohne Verifikation kann jeder gefälschte Webhooks schicken.
• Secrets rotieren: Bei Kompromittierung Subscription löschen und neu anlegen.