knowmindknowmind
DokumentationQuickstartAnbindungReferenzFehlerbehebung
DEEN

Aufgaben

Webhooks einrichten

knowmind sendet auf Wunsch HTTP-POSTs an Ihre URL, sobald in Ihrem Arbeitsbereich etwas passiert: neue Erinnerung, neue Beziehung, Tarif-Wechsel. Diese Anleitung führt durch Anlage, Signatur-Prüfung und Retry-Verhalten.

Zielgruppe
Entwicklerinnen und Entwickler im Tarif Business API oder Enterprise. Vorkenntnisse in HTTP, JSON und HMAC-Signaturen sind hilfreich.

Voraussetzungen

  • knowmind-Konto im Tarif Business API oder Enterprise
  • Erreichbarer HTTPS-Endpunkt unter Ihrer Kontrolle (z. B. eigene API, n8n-Webhook-Node, Zapier-Webhook)
  • Möglichkeit, ein Geheimnis (Secret) sicher zu speichern

Schritte

  1. 1

    Webhook im Dashboard anlegen

    Im Dashboard auf Webhooks, dann „Webhook anlegen". URL eintragen (HTTPS Pflicht), gewünschte Events auswählen, optional eine Beschreibung. Auf „Anlegen" klicken.

    Ergebnis: knowmind zeigt das HMAC-Secret einmalig an — sofort kopieren und sicher ablegen. Danach ist es nicht mehr abrufbar.

  2. 2

    Test-Event auslösen

    In der Liste der Webhooks auf den Test-Knopf neben dem neuen Eintrag klicken. knowmind sendet einen Webhook vom Typ webhook.test.

    Ergebnis: Im Log Ihres Endpunkts erscheint die Test-Anfrage.

  3. 3

    Signatur prüfen

    Jeder Webhook enthält im Header X-knowmind-Signature den Wert sha256=<hex> — das ist HMAC-SHA256 des unveränderten Roh-Bodys mit Ihrem Secret als Schlüssel. Verifizieren Sie die Signatur immer, bevor Sie den Inhalt verarbeiten.

    ts
    // 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
    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

    Retry-Verhalten verstehen

    knowmind erwartet HTTP-2xx innerhalb von 15 Sekunden. Alles andere (Timeout, 4xx, 5xx) löst einen Retry aus mit exponentiellem Backoff: sofort, dann nach 1 Minute, 5 Minuten, 30 Minuten, 2 Stunden, 12 Stunden. Nach sechs Fehlversuchen wird die Lieferung als dead markiert. Nach 20 aufeinanderfolgenden Fehlern wird die gesamte Subscription deaktiviert.

Prüfung des Ergebnisses

  • Im Dashboard zeigt der Webhook unter „Letzter Erfolg" einen aktuellen Zeitpunkt.
  • Ihr Endpunkt hat die Test-Anfrage protokolliert.
  • Die Signatur-Verifikation in Ihrem Endpunkt gibt true zurück.

Fehlerbehebung

FehlermeldungUrsacheAuflösung
Webhook-Anlage zeigt „Im Tarif nicht enthalten"Aktueller Tarif unterhalb Business API.Auf Business API oder Enterprise wechseln.
Signatur stimmt nicht übereinRoh-Body wurde von einem Framework verändert (Trimming, Re-Serialisierung).Im Handler den exakten Roh-Body als String/Bytes verwenden, nicht das schon geparste JSON. In Express: bodyParser.raw({ type: 'application/json' }). In Next.js: req.text() vor JSON-Parsing.
Webhook wird nicht zugestelltEndpunkt liefert kein 2xx innerhalb 15 Sekunden — knowmind probiert es später erneut.Sofort 2xx zurückgeben, Verarbeitung in eine Hintergrund-Queue verschieben. Header X-knowmind-Delivery als Idempotenz-Schlüssel verwenden, damit Retries keine doppelte Verarbeitung verursachen.
Subscription deaktiviert20 aufeinanderfolgende Fehler.Ursache am eigenen Endpunkt beheben, im Dashboard die Subscription manuell reaktivieren.

Weiterführend