Webhooks

Docsbook kann Ihre Systeme über Ereignisse informieren, die innerhalb eines Arbeitsbereichs auftreten — neu indizierte Inhalte, benötigte Übersetzungen, gestellte Chat-Fragen, Verkehrsanomalien und mehr. Jeder Webhook ist typisiert: Sie abonnieren eines von 18 spezifischen Ereignissen, und Docsbook sendet nur dann eine POST-Anfrage an Ihre URL, wenn genau dieses Ereignis ausgelöst wird.

Die Registrierung eines Webhooks und der Empfang seiner Zustellungen werden nicht vom Guthaben des Projekts abgezogen. Zustellungen, die Sie manuell erneut abspielen oder testen, werden als Egress abgerechnet, da jede davon ein ausgehender Aufruf ist, den Docsbook in Ihrem Namen tätigt.

Funktionsweise#

1. Du registrierst einen Webhook mit event_type, url und einem optionalen secret.
2. Wenn das Ereignis eintritt, stellt Docsbook eine Zustellung in die Warteschlange (Outbox-Muster).
3. Der Worker (Vercel-Cronjob, jede Minute) sendet den JSON-Body per POST an deine URL.
4. Wir wiederholen den Vorgang bis zu 3-mal mit exponentiellem Backoff (1 s, 10 s, 60 s).

Anforderungsformat#

POST https://your-url.example.com
Content-Type: application/json
User-Agent: Docsbook-Webhooks/1.0
X-Docsbook-Event: content.indexed
X-Docsbook-Signature-256: sha256=<hex hmac of body>
X-Docsbook-Delivery: 12345
X-Docsbook-Attempt: 1

{
  "event": "content.indexed",
  "workspace_id": 42,
  "occurred_at": "2026-05-23T12:34:56.000Z",
  "data": { /* event-specific payload */ }
}

Signaturen überprüfen#

import crypto from "node:crypto"
const expected = "sha256=" + crypto.createHmac("sha256", SECRET).update(rawBody).digest("hex")
if (expected !== req.headers["x-docsbook-signature-256"]) reject()

Eine 2xx-Antwort = zugestellt. Alles andere löst Wiederholungsversuche aus, bis das Versuchslimit ausgeschöpft ist.

Sehen, was Ihr Arbeitsbereich ausgibt#

Das Feeds-Panel in Ihrer Administration zeigt jedes Ereignis an, das der Arbeitsbereich erzeugt hat, wobei die neuesten zuerst angezeigt werden — einschließlich Ereignissen, die von keinem Alarm überwacht wurden, sowie jedem MCP-Tool-Aufruf, der an ihn gerichtet wurde. Sie müssen keinen Webhook registriert haben, um zu sehen, wie sich der Feed füllt. Genau darum geht es: So finden Sie heraus, welche Ereignisse Ihre Dokumentation tatsächlich ausgibt, bevor Sie entscheiden, worüber Sie benachrichtigt werden möchten. Der Feed ist live — er aktualisiert sich alle paar Sekunden automatisch, während Sie ihn ansehen. Daher müssen Sie keinen Zeitraum auswählen und nicht daran denken, ihn neu zu laden.

Einen Feed auswählen#

Der Bereich Feeds öffnet eine Seite mit Karten – eine pro Feed, jeweils mit einer Zeile, die beschreibt, was er enthält, sowie am Ende einer Karte Eigenen Feed erstellen. Wenn du eine Karte öffnest, wechselst du direkt zu diesem Feed, ohne Titel oder Zurück-Link darüber: Du bist durch die Auswahl einer Karte hierher gelangt, und die Seitenleistenzeile für Feeds bringt dich zu ihnen zurück.

Dieselben Feeds werden auch als Zeilen unter diesem Seitenleistenbereich angezeigt, um zwischen ihnen zu wechseln, ohne den gerade gelesenen Feed zu verlassen – diese Liste ist jedoch zunächst geschlossen. Bewege den Mauszeiger über die Zeile Feeds, worauf ein Chevron-Symbol das bisherige Symbol ersetzt; klicke darauf, um bis zu fünf Feeds anzuzeigen, die zuletzt geöffneten zuerst, mit Weitere N anzeigen für die übrigen. Docsbook merkt sich, ob du die Liste geöffnet gelassen hast, wenn du das nächste Mal zurückkehrst. Der +, der aus einem leeren Filter eine neue Liste erstellt, befindet sich sowohl in dieser Zeile als auch als Karte in der Übersicht.

Sieben Feeds sind standardmäßig vorhanden, sodass du bei deinem ersten Besuch etwas öffnen kannst, bevor du selbst etwas gespeichert hast: Leserereignisse (alles, was Personen beim Lesen deiner Dokumentation getan haben – gelesene Seiten, ausgeführte Suchen, an die KI gestellte Fragen, abgegebenes Feedback), Übersetzungen (jede erzeugte Sprache, veraltet oder noch benötigt), Sprachereignisse (in welche Sprachen Leser die Dokumentation umschalten), Chatereignisse (Fragen an den KI-Assistenten, bei denen er keine Antwort hatte, sowie Antworten, die mit einem Daumen nach unten bewertet wurden), Leserfeedback (Daumen-nach-unten-Bewertungen und Kommentare zu einer Seite oder einer Antwort), MCP-Aufrufe (jeder abgerechnete Aufruf eines Agenten) und Alle Ereignisse – alles, ungefiltert, als letzter Eintrag in der Liste, da du diesen Feed verwendest, wenn keiner der benannten passt. Leserereignisse, Sprachereignisse und MCP-Aufrufe sind Feeds zum Lesen und nicht zum Abonnieren, da an keines ihrer Ereignisse ein Alarm angehängt werden kann; die anderen vier sind genau die Feeds, auf die du einen Benachrichtigungsdienst richten würdest. Alle sieben sind Ausgangsfilter statt gespeicherter Listen, können also nicht gelöscht werden, und es kann nichts direkt auf einen von ihnen verweisen – schränke einen ein, und Als Liste speichern macht daraus einen eigenen Feed, der als eigene Zeile erscheint und die Form hat, an die ein Alarm angehängt werden kann.

Feed lesen#

Der Feed ist in Tagesabschnitte gegliedert, und jeder Eintrag besteht aus einer Zeile: dem Avatar des Lesers, wenn ein Leser das Ereignis ausgelöst hat (einem Plan-, Nutzungs- oder MCP-Ereignis kann niemand zugeordnet werden), einer farbigen Kachel für seinen Typ, dem Namen des Ereignisses, der einzeiligen Zusammenfassung und dem Ziel. Status, Ereignistyp und Ziel werden als kleine Symbole angezeigt, wobei das Wort mit einem Klick in einem Popover erreichbar ist, sodass alles in einer Zeile bleibt. Die Zeiten werden als Uhrzeiten angezeigt, da der Tag bereits durch den darüberstehenden Abschnitt angegeben ist. Durch Klicken auf eine Zeile wird sie an Ort und Stelle erweitert und zeigt das vollständige Ereignis – jeden Zustellversuch mit seiner Antwort, die erneute Zustellung und die rohen Nutzdaten. Ein Ereignis hat einen einzigen Status, der aus seinen Zustellungen zusammengeführt wird, wobei das schlechteste Ergebnis gewinnt:

MCP-Tool-Aufrufe im Feed#

Der Feed zeigt außerdem jeden MCP-Tool-Aufruf, den ein Agent in diesem Arbeitsbereich ausgeführt hat, zusammen mit den Ereignissen, die Ihre Dokumente ausgelöst haben. Eine Zeile pro Aufruf: das aufgerufene Tool, ob es funktioniert hat, wie lange es gedauert hat und was es zum Listenpreis auf der MCP-Preisliste gekostet hat. Fehlgeschlagene Aufrufe werden als solche gekennzeichnet. Aufrufe, die sich auf kein bestimmtes Projekt bezogen — etwa die Beschreibung des Servers, das Auflisten Ihrer Projekte oder das Erstellen eines Projekts — gehören zu Ihrem Konto und nicht zu einem Projekt und erscheinen daher in keinem Projekt-Feed.

Sie werden standardmäßig angezeigt; es muss nichts aktiviert werden. Im Auswahlfeld Ereignis hinzufügen befinden sie sich in einem eigenen Abschnitt MCP-Aufrufe, gefiltert nach der Abrechnungsklasse des Aufrufs — mcp.read, mcp.write, mcp.query, mcp.egress, mcp.generate, mcp.agent — und nicht nach dem Toolnamen, denn diese Achse verursacht Kosten und bleibt auch bei der Veröffentlichung neuer Tools zuverlässig. Der eigene Name des Tools steht in jeder Zeile und in jedem Payload, sodass das Filtern nach einem einzelnen Tool nur eine Payload-Suche entfernt ist. Kostenlose Aufrufe (get_info, find_skill, find_widget und der Rest der Erkennung) werden niemals erfasst und hinterlassen daher keine Zeile.

Ein Tool-Aufruf wurde nie irgendwohin weitergeleitet, daher wird er als nicht gesendet angezeigt und verschwindet wie Leseraktivitäten sofort, sobald Sie nach Ziel oder Zustellstatus filtern. Auch das Anheften eines Besuchers lässt ihn verschwinden: Ein Agent, der ein Token verwendet, ist keiner Ihrer Leser, und es wäre falsch, seine Aufrufe als Browsing einer Person zu zählen.

Feed eingrenzen#

Filtern Sie den Feed nach Ereignistyp, Status, Ziel, Besucher, einem abgeschlossenen Ziel oder freiem Text, der an beliebiger Stelle in der Nutzlast vorkommt — eine Symbolleistenzeile über dem Feed, ohne darüberstehende Überschrift. Die ersten fünf Facetten sind Symbolschaltflächen: Bewegen Sie den Mauszeiger darüber oder fokussieren Sie sie, um ihren Namen zu sehen. Sobald eine Facette festgelegt ist, wird sie mit dem Wert selbst ausgefüllt, und durch Klicken auf diesen Wert können Sie sie erneut bearbeiten. Freier Text befindet sich als eigenes, immer sichtbares Suchfeld am Ende dieser Zeile und nicht als Facette, die Sie zuerst öffnen müssen. Ein Besucherfilter ist nur einen Klick von Analytics entfernt — öffnen Sie dort einen Leser und springen Sie direkt zu allem, was er getan hat —, nur einen Klick vom eigenen Avatar einer Zeile im Feed entfernt oder kann manuell durch Einfügen einer ID gesetzt werden. Durch das Anheften eines Lesers erweitert sich der Suchbereich des Feeds: Neben den Ereignissen, die Ihre Dokumentation ausgelöst hat, werden auch die eigenen Aktivitäten dieses Lesers auf der Website abgerufen — die von ihm gelesenen Seiten, wonach er gesucht und was er gefragt hat —, sodass ein angehefteter Feed alles enthält, was dieser Leser getan hat, und nicht nur die Teile, die eine Benachrichtigung hätten auslösen können. Außerdem wird über dem Feed eine Karte angezeigt, die angibt, wer dieser Leser ist: von wo aus er gelesen hat, auf welchem Gerät, mit welchem System und Browser, in welcher Sprache er gelesen hat, zu welcher Seite er immer wieder zurückkehrt, wie lange er insgesamt Ihre Dokumentation gelesen hat, welche Ziele er erreicht hat und welchen Wert er heute hat sowie welchen Wert er möglicherweise noch erreichen kann. Die Karte gilt nur für einen einzelnen angehefteten Leser, da ein Zielfilter eine Gruppe umfasst und ein Land sowie ein Browser, gemittelt über eine Gruppe, niemanden beschreiben. Beim Speichern eines Filters wird dieser zu einer Ereignisliste — das Eingrenzen des Feeds und das Festlegen, worüber Sie benachrichtigt werden möchten, sind somit dieselbe Aktion. Test-Pings erscheinen wie jedes andere Ereignis im Feed; eine Wiederholung wird als weiterer Versuch unter dem Ereignis angezeigt, zu dem sie gehört. Exportieren lädt genau das herunter, was Sie gerade betrachten, mit angewendeten Filtern und ohne zeitliche Begrenzung, als CSV, JSON oder NDJSON — ohne zeitliche Begrenzung, weil der Feed selbst keinen Zeitraum umfasst: Er ist live, und eine Datei, die enger gefasst ist als die Ansicht, die sie kopiert, ist schlechter als gar keine Datei. Die Option befindet sich am Ende derselben Symbolleistenzeile neben Prompt einrichten und Benachrichtigung einrichten — den drei Steuerelementen, die auf die gesamte Ansicht und nicht auf ein einzelnes Ereignis wirken.

Einen Prompt für einen Feed ausführen lassen#

Ein Alert leitet die Ereignisse eines Feeds an eine Person weiter. Prompt einrichten daneben in derselben Zeile übergibt sie stattdessen an deinen Assistenten: Wähle einen Prompt aus, und er wird jedes Mal automatisch ausgeführt, wenn etwas in diesem Feed eintrifft – ganz ohne Überwachung. Die Schaltfläche zeigt eine Anzahl an, sodass ein Feed mit Inhalten nie wie ein Feed ohne Inhalte aussieht, und jeder aktivierte Prompt erhält neben den Ziel-Chips einen Chip — ausgefüllt, während er ausgeführt wird, leer, während er pausiert ist, mit seinem letzten Lauf im Tooltip.

Durch Klicken auf einen Chip werden nicht dessen Einstellungen geöffnet. Stattdessen wird die Unterhaltung geöffnet, die der Prompt geführt hat: das Protokoll dessen, was er beim letzten Ändern dieses Feeds tatsächlich getan hat, in der Gruppe „Trigger“ des Assistenten. Nur daran kannst du erkennen, dass ein Prompt funktioniert, statt lediglich aktiviert zu sein.

Was einen Feed überwacht, überwacht einen gespeicherten Feed. Eine Ansicht, die du eingegrenzt, aber noch nicht gespeichert hast, weist darauf hin und verweist auf Als Liste speichern. Dieselbe Aktivierung ist auch von der anderen Seite aus verfügbar — im Bereich Nach Zeitplan oder einem Ereignis auf der eigenen Seite eines MCP-Tools werden deine Feeds über den einzelnen Ereignissen aufgelistet — und beim Löschen eines Feeds wird die Überwachung aufgehoben, statt den aktivierten Aufruf zu löschen.

Was alles gekostet hat#

Jede Zeile im Feed hat einen Preis, und eine Zeile nach der anderen ist keine Spalte, die jemand addieren kann. Nutzung anzeigen auf der Guthabenkarte in der Seitenleiste ersetzt den Stream durch die Summe: wofür das Geld dieses Projekts in einem Zeitraum ausgegeben wurde, absteigend nach Kosten, in drei Abschnitten. Sie befindet sich nicht in der eigenen Symbolleiste des Feeds, weil die Zahl das gesamte Projekt betrifft und nicht den Feed, den Sie gerade ansehen.

Die ersten beiden werden berechnet: Dieses Geld wurde vom Guthaben des Projekts abgezogen. Das dritte wird nicht berechnet – Ereignisse werden mit einem Preis versehen, damit der Datenverkehr nicht unsichtbar bleibt, und für sie wird nichts abgezogen. Daher werden die beiden Summen als zwei Zahlen unter zwei verschiedenen Bezeichnungen angezeigt, und jeder Abschnitt trägt ein charged- oder not charged-Abzeichen, denn eine Zahl, die alle drei abdeckt, wäre eine Rechnung für Geld, das niemand genommen hat.

Wählen Sie einen Zeitraum von 24 Stunden, 7 Tagen oder 30 Tagen. Es gibt keinen längeren Zeitraum, weil es nichts Längeres zu lesen gibt: Leseranalyse-Daten werden 30 Tage lang aufbewahrt und das KI-Ledger wird entsprechend bereinigt, sodass eine Schaltfläche für 90 Tage Daten für 30 Tage liefern würde, aber unter der falschen Bezeichnung.

Exportieren bietet hier die Aufschlüsselung selbst als CSV-Datei an – eine Zeile pro Modell, Tool oder Ereignistyp, mit der Anzahl und den Kosten als einfache Zahl, die Sie summieren können, sowie einer Spalte, die angibt, ob diese Zeile berechnet wurde – ebenso wie die zugrunde liegenden Rohereignisse, begrenzt durch den Zeitraum, den Sie gerade betrachten.

Dieser Bildschirm wird auch über Nutzung anzeigen aus dem Guthabenhinweis der Seitenleiste geöffnet – der Karte, die warnt, wenn das Guthaben dieses Projekts knapp wird. Das Aufladen befindet sich im Block Guthaben des Kontomenüs: Der eine beantwortet die Frage, wie viel übrig ist, dieser hier, wofür es ausgegeben wurde.

Notifier: Wohin Ereignisse gehen#

Ein Notifier ist ein Ziel – ein Kanal, seine URL und seine Zugangsdaten – und existiert unabhängig von den Ereignissen, die er überträgt. Sie erstellen ihn einmal – über Alarm einrichten in der Titelleiste oder über Neuer Notifier am unteren Ende von Notifier hinzufügen – und aktivieren ihn dann für so viele Ereignislisten, wie er bedienen soll. Ein Slack-Kanal, der von drei Listen gespeist wird, ist ein Notifier mit einem Signaturgeheimnis, der an einer einzigen Stelle pausiert oder gelöscht wird.

Die Notifier, die für die angezeigte Liste bereits aktiv sind, stehen neben den Filter-Chips als eigene beschriftete Chips – jeder mit dem echten Symbol seines Kanals, seinem Namen und paused, wenn er deaktiviert ist. Wenn Sie auf einen klicken, wird dieser Notifier geöffnet. So können Sie sehen, wohin eine Liste liefert, und ihn ändern, ohne den Feed zu verlassen. Einen Notifier, der für eine andere Liste aktiv ist – oder für keine, wie es bei jedem neuen Notifier der Fall ist –, erreichen Sie über das Menü Notifier hinzufügen, in dem jede Zeile neben ihrer Checkbox ein Steuerelement zum Bearbeiten enthält.

Deaktivieren Sie eine Liste, wird der Notifier für sie nicht mehr ausgelöst. Deaktivieren Sie die letzte Liste, bleibt das Ziel bestehen, ist jedoch nirgendwo zugeordnet und liefert nichts, bis Sie es wieder einer Liste zuweisen. Beim Löschen einer Ereignisliste geschieht dasselbe mit allem, was für sie aktiv war – ein Abonnement wird durch den Verlust seiner Liste niemals erweitert.

Nur gespeicherte Listen können bedient werden: Die integrierten Feeds, darunter Alle Ereignisse, sind Filter und keine Listen. Speichern Sie den gewünschten Feed daher zuerst als eigenen Feed.

Ereigniskatalog#

Ein Docsbook-Arbeitsbereich gibt 18 typisierte Ereignisse aus. Jede Zeile unten benennt das Ereignis genau so, wie es im X-Docsbook-Event-Header und im event-Feld des Textkörpers erscheint, zusammen mit den Feldern, die sein data-Objekt enthält.

Drei der achtzehn sind als erweitert gekennzeichnet — traffic.spike, traffic.drop und mcp.tool_called. Jedes davon wird aus einer Baseline oder aus gemessener Aktivität abgeleitet, anstatt direkt durch eine Aktion ausgelöst zu werden.

Webhook registrieren#

Über REST#

curl -X POST https://docsbook.io/api/webhooks \
  -H "Content-Type: application/json" \
  -d '{"workspace_id": 42, "event_type": "content.indexed", "url": "https://you.example.com/hook"}'

Die Antwort enthält secret genau einmal — speichern Sie ihn.

event_type akzeptiert beide Schreibweisen eines Ereignisnamens: die auf dieser Seite durchgehend verwendete Punktnotation (content.indexed) oder die Schreibweise mit Unterstrichen (content_indexed). Beide registrieren dasselbe Abonnement.

Optionaler Authorization-Header#

Einige Empfänger (zum Beispiel eine Claude-Code-Routine-Trigger-URL) benötigen bei jeder Anfrage ihr eigenes Bearer-Token, getrennt von der HMAC-Signaturüberprüfung. Übergeben Sie auth_header beim Erstellen des Webhooks, und Docsbook sendet es bei jeder Zustellung unverändert als Authorization-Header:

curl -X POST https://docsbook.io/api/webhooks \
  -H "Content-Type: application/json" \
  -d '{"workspace_id": 42, "event_type": "content.indexed", "url": "https://you.example.com/hook", "auth_header": "Bearer sk-..."}'

Wenn der Wert kein Leerzeichen enthält, wird er als Bearer <value> gesendet; wenn er bereits ein Schema enthält (z. B. Bearer sk-...), wird er unverändert gesendet.

Über MCP#

Jedes Ereignis verfügt über ein eigenes MCP-Tool, sodass ein KI-Agent einen bestimmten Benachrichtigungsstream abonnieren kann, ohne Zeichenfolgen auswählen zu müssen:

register_webhook_content_indexed(workspace_id: 42, url: "https://YOUR_ENDPOINT")
register_webhook_translation_needed(repo: "owner/repo", url: "https://YOUR_ENDPOINT")
register_webhook_traffic_spike(workspace_id: 42, url: "https://YOUR_ENDPOINT")

Weitere MCP-Tools mit der Abrechnungsklasse, unter der jeder Aufruf verbucht wird:

REST-Endpunkte#

• GET /api/webhooks?workspace_id=X — auflisten
• POST /api/webhooks — erstellen
• PATCH /api/webhooks/:id — umbenennen, pausieren/fortsetzen oder auf eine andere Ereignisliste verweisen
• POST /api/webhooks/:id/attach — { "list_id": N }, eine weitere Liste über dasselbe Ziel (dieselbe URL, dasselbe Secret) bereitstellen
• DELETE /api/webhooks/:id — löschen
• POST /api/webhooks/:id/test — Ping testen
• GET /api/webhooks/:id/deliveries — letzte Zustellungen
• POST /api/webhook-deliveries/:id/replay — eine vorhandene Zustellung erneut in die Warteschlange einreihen

Semantik von Wiederholungen und Fehlern#

• Der Worker wird jede Minute über Vercel Cron ausgeführt.
• Eine Zustellung wird bis zu 3-mal versucht.
• Das Backoff wird anhand von created_at der Zeile durchgesetzt: 1 s, 10 s, 60 s.
• Nach dem 3. Fehler → status = "failed". Verwende replay_webhook_delivery, um es erneut zu versuchen.
• Der Antwortcode und der (gekürzte) Antworttext werden bei jeder Zustellungszeile gespeichert.

Verwandte Inhalte#

• Referenz zu MCP-Tools — die register_webhook_<event>-Tools und alle anderen Tools auf dem Server
• Übersicht über den MCP-Server — Verbindung eines Clients und die Preisliste, nach der der Feed Aufrufe abrechnet
• Referenz zu erfassten Ereignissen — die Leseraktionen hinter mehreren dieser Ereignisse
• Überblick über Analysen — dieselben Aktivitäten als Bericht statt als Stream lesen