Die Webhook-Schnittstelle

Diese Seite beschreibt, wie ein sendendes System Inhalte an eine Webhook-Quelle übergibt. Sie ist als Unterlage für die Personen gedacht, die diese Anbindung bauen — im eigenen Haus oder bei einem beauftragten Dienstleister. Wie eine Webhook-Quelle angelegt wird und wofür sie gedacht ist, steht auf der Seite Webhook-Quellen.

Das Wichtigste in einem Satz: Ob eine Sendung ein bestehendes Dokument aktualisiert oder ein zweites daneben anlegt, entscheidet allein das Wiedererkennungsmerkmal — und wenn Sie keines mitgeben, ist es der Dokumentname.

Was Sie vorher brauchen

Beides erhalten Sie von der Person, die den Arbeitsbereich verwaltet:

die Adresse der Quelle, in der Form https://<ihre-adresse>/ingest/knowledge/webhook/<quellen-kennung>
den Schlüssel der Quelle

Der Schlüssel gehört zu genau einer Quelle und damit zu genau einem Ordner. Er wird beim Anlegen ein einziges Mal angezeigt und lässt sich später nur ersetzen, nicht auslesen.

Die Anfrage

POST https://<ihre-adresse>/ingest/knowledge/webhook/<quellen-kennung>
Content-Type: application/json
X-Webhook-Token: <schlüssel>

Der Rumpf ist ein JSON-Objekt mit drei Feldern:

Feld	Pflicht	Inhalt
`title`	ja	Der Name, unter dem das Dokument in der Oberfläche erscheint
`markdown`	ja	Der Inhalt als Markdown-Text, UTF-8 kodiert
`externalRef`	nein	Das Wiedererkennungsmerkmal — siehe den nächsten Abschnitt

json

{
  "title": "Wochenplan der Abteilung III",
  "externalRef": "fachverfahren:wochenplan-abt-3",
  "markdown": "# Wochenplan\n\n## Montag\n..."
}

Aktualisieren statt vermehren

Die Plattform kennt keinen getrennten Aufruf zum Anlegen und zum Ändern. Jede Sendung geht an dieselbe Adresse, und die Plattform entscheidet selbst:

Existiert in dieser Quelle bereits ein Dokument mit demselben Wiedererkennungsmerkmal, wird es ersetzt. Sonst wird ein neues angelegt.

Das Merkmal ist also der Schlüssel des Dokuments, nicht sein Name. Beim Ersetzen bleibt das Dokument dasselbe: Der Inhalt, der Name, die Größe und der Zeitstempel werden überschrieben, alte Textabschnitte werden entfernt, und die vorige Fassung ist danach auch für die Suche nicht mehr auffindbar.

Wenn Sie kein Merkmal mitgeben

Lassen Sie externalRef weg, bildet die Plattform es aus dem Dokumentnamen: aus dem Titel Wochenplan wird das Merkmal webhook:Wochenplan. Dann entscheidet der Dokumentname über Aktualisieren oder Anlegen — und zwar zeichengenau:

Was Sie senden	Ergebnis
`externalRef` gesetzt, bei jeder Sendung gleich	Das bestehende Dokument wird aktualisiert
kein `externalRef`, Titel zeichengleich wie zuvor	Das bestehende Dokument wird aktualisiert
kein `externalRef`, Titel um ein Zeichen verändert	Ein zweites Dokument entsteht, das alte bleibt bestehen
`externalRef` gesetzt, aber verändert	Ein zweites Dokument entsteht, das alte bleibt bestehen

Zeichengenau heißt: Groß- und Kleinschreibung, Satzzeichen, ein zusätzliches Leerzeichen am Ende — jede Abweichung ist ein anderes Dokument. Der häufigste Fehler in der Praxis ist ein Datum im Titel: Wochenplan 2026-09-08 und Wochenplan 2026-09-15 sind zwei Dokumente, und nach einem Jahr stehen zweiundfünfzig Fassungen nebeneinander, ohne dass die Suche wissen kann, welche gilt.

Die Empfehlung

Geben Sie immer ein eigenes externalRef mit — eine kurze, dauerhaft gleichbleibende Zeichenkette aus Ihrem eigenen System, etwa fachverfahren:wochenplan-abt-3 oder register:kunde-4711. Behandeln Sie title als reinen Anzeigetext.

Das trennt zwei Dinge, die sonst aneinanderkleben: Sie können ein Dokument jederzeit umbenennen, indem Sie dasselbe Merkmal mit einem neuen Titel senden — das Dokument bleibt dasselbe und bekommt nur einen neuen Namen. Und Sie können den Titel um ein Datum ergänzen, ohne dass der Bestand wächst.

Ein Merkmal gilt innerhalb einer Quelle. Dieselbe Zeichenkette an eine zweite Webhook-Quelle gesendet ergibt ein zweites, eigenständiges Dokument in deren Ordner.

Beispiele

bash

curl -X POST "https://<ihre-adresse>/ingest/knowledge/webhook/<quellen-kennung>" \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Token: <schlüssel>" \
  -d '{
        "title": "Wochenplan der Abteilung III",
        "externalRef": "fachverfahren:wochenplan-abt-3",
        "markdown": "# Wochenplan\n\n## Montag\n..."
      }'

python

import requests

requests.post(
    f"https://{host}/ingest/knowledge/webhook/{quellen_kennung}",
    headers={"X-Webhook-Token": schluessel},
    json={
        "title": "Wochenplan der Abteilung III",
        "externalRef": "fachverfahren:wochenplan-abt-3",
        "markdown": markdown_text,
    },
    timeout=120,
).raise_for_status()

powershell

$body = @{
  title       = "Wochenplan der Abteilung III"
  externalRef = "fachverfahren:wochenplan-abt-3"
  markdown    = $markdownText
} | ConvertTo-Json

Invoke-RestMethod -Method Post `
  -Uri "https://$host/ingest/knowledge/webhook/$quellenKennung" `
  -Headers @{ "X-Webhook-Token" = $schluessel } `
  -ContentType "application/json; charset=utf-8" `
  -Body $body

Die Antwort

Eine erfolgreiche Sendung wird mit 200 und einem JSON-Objekt beantwortet:

json

{
  "document_id": "665f…",
  "chunk_count": 12,
  "external_ref": "fachverfahren:wochenplan-abt-3",
  "content_hash": "9f2b…",
  "commit_state": "committed"
}

external_ref zeigt, unter welchem Merkmal das Dokument tatsächlich abgelegt wurde — der schnellste Weg, eine falsch verstandene Zuordnung zu erkennen. content_hash ist die Prüfsumme über den gesendeten Text; wer sie mitschreibt, erkennt eine unveränderte Sendung schon vor dem nächsten Aufruf.

Wenn etwas schiefgeht

Antwort	Bedeutung	Was zu tun ist
`400`	Der Inhalt ist leer	Sendung im eigenen System unterdrücken
`401`	Schlüssel fehlt oder passt nicht zu dieser Quelle	Schlüssel und Adresse prüfen — beide gehören zusammen
`413`	Der Inhalt überschreitet 20 MiB	Dokument aufteilen
`422`	Der Aufbau passt nicht, oder es entstand kein verwertbarer Abschnitt	Feldnamen prüfen; bei sehr kurzen Inhalten den Text prüfen
`502`	Eine nachgelagerte Verarbeitung ist ausgefallen	Später erneut senden — siehe unten
`503`	Der Habicht-Support hat kein Verarbeitungsmodell hinterlegt	Beim Habicht-Support melden, erneutes Senden hilft nicht

Erneutes Senden ist unbedenklich. Kommt zweimal derselbe Inhalt unter demselben Merkmal an, erkennt die Plattform das und legt nichts doppelt an. Bei 502 warten Sie zwischen den Versuchen zunehmend länger, statt in kurzem Takt zu wiederholen — die Verarbeitung ist die gemeinsam genutzte Engstelle.

Unverändert erneut zu senden ist zwar folgenlos, aber nicht kostenlos: Der Text wird trotzdem vollständig verarbeitet, bevor die Plattform merkt, dass sich nichts geändert hat. Wer im Takt sendet, vergleicht besser vorher die eigene Prüfsumme und lässt die Sendung ganz aus.

Grenzen

20 MiB je Sendung für das Feld markdown.
Ein Dokument je Anfrage. Es gibt keine Sammelsendung; senden Sie nacheinander, nicht in vielen gleichzeitigen Verbindungen.
Zwei Minuten Antwortzeit. Ein sehr großes Dokument kann darüber laufen; die Verbindung bricht dann ab, obwohl die Verarbeitung unter Umständen noch fertig wird. Halten Sie einzelne Dokumente im niedrigen einstelligen Megabyte-Bereich.
Nur Markdown. Die Schnittstelle erwartet fertigen Text. Dateien in anderen Formaten gehören in eine Upload- oder Sammelquelle.
Löschen ist nicht vorgesehen. Der Webhook legt an und ersetzt. Hört ein System auf, ein Merkmal zu senden, bleibt dessen Dokument unbegrenzt liegen und beantwortet weiter Fragen. Entfernt wird es in der Oberfläche.
Die Sendung trägt kein Datum. Soll der Stand erkennbar sein, muss er im Text stehen — im Titel nur dann, wenn Sie ein eigenes externalRef mitgeben.

Vor der Inbetriebnahme

Ist für jedes Dokument ein dauerhaft gleichbleibendes externalRef festgelegt, das aus dem sendenden System abgeleitet wird?
Ist der Titel frei von allem, was sich je Sendung ändert — oder ist das unschädlich, weil ein eigenes Merkmal mitgeht?
Wird eine zweite Sendung desselben Dokuments getestet, und liegt danach ein Dokument im Ordner, nicht zwei?
Wird die Antwort ausgewertet? Ein 401 nach einem Schlüsselwechsel sieht in der Oberfläche nach nichts aus — dort kommt einfach nichts mehr an.
Liegt der Schlüssel in einem Passwortspeicher und nicht im Quelltext?

Die Webhook-Schnittstelle

Was Sie vorher brauchen ​

Die Anfrage ​

Aktualisieren statt vermehren ​

Wenn Sie kein Merkmal mitgeben ​

Die Empfehlung ​

Beispiele ​

Die Antwort ​

Wenn etwas schiefgeht ​

Grenzen ​

Vor der Inbetriebnahme ​