Webhooks

Docsbook peut notifier vos systèmes des événements qui se produisent au sein d’un espace de travail — nouveau contenu indexé, traductions nécessaires, questions posées dans le chat, anomalies de trafic et bien plus encore. Chaque webhook est typé : vous vous abonnez à l’un des 18 événements spécifiques, et Docsbook envoie une requête POST à votre URL uniquement lorsque cet événement précis se déclenche.

L’enregistrement d’un webhook et la réception de ses livraisons ne coûtent rien sur le solde du projet. Les livraisons que vous rejouez ou testez manuellement sont comptabilisées comme du trafic sortant, car chacune d’elles correspond à un appel sortant effectué par Docsbook en votre nom.

Fonctionnement#

1. Vous enregistrez un webhook avec event_type, url et un secret facultatif.
2. Lorsque l’événement se produit, Docsbook met une livraison en file d’attente (modèle outbox).
3. Le worker (cron Vercel, chaque minute) envoie le corps JSON à votre URL via POST.
4. Nous réessayons jusqu’à 3 tentatives avec un délai exponentiel (1 s, 10 s, 60 s).

Format de la requête#

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 */ }
}

Vérification des signatures#

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()

Une réponse 2xx = livrée. Toute autre réponse déclenche une nouvelle tentative jusqu'à épuisement du budget de tentatives.

Voir ce que votre espace de travail émet#

Le panneau Flux de votre espace d'administration affiche chaque événement produit par l'espace de travail, du plus récent au plus ancien — y compris les événements qu'aucune alerte ne surveillait, ainsi que chaque appel d'outil MCP effectué sur celui-ci. Vous n'avez pas besoin d'avoir enregistré un webhook pour voir le flux se remplir, et c'est précisément le but : c'est ainsi que vous découvrez quels événements vos documents émettent réellement avant de décider des événements dont vous souhaitez être informé. Le flux est en direct — il s'actualise automatiquement toutes les quelques secondes pendant que vous le consultez, vous n'avez donc aucune plage temporelle à sélectionner ni aucun rechargement à ne pas oublier.

Choisir un flux#

La section Flux s'ouvre sur une page de cartes — une par flux, chacune indiquant ce qu'elle contient, ainsi qu'une carte Créer votre propre flux à la fin. Ouvrir une carte bascule vers ce flux lui-même, sans titre ni lien de retour au-dessus : vous êtes arrivé ici en choisissant une carte, et la ligne latérale Flux permet de revenir à la liste.

Ces mêmes flux apparaissent également sous forme de lignes dans cette section de la barre latérale, pour passer de l'un à l'autre sans quitter celui que vous consultez — mais cette liste commence fermée. Survolez la ligne Flux et un chevron remplace son icône ; cliquez dessus pour afficher jusqu'à cinq flux, en commençant par les plus récemment ouverts, avec Afficher N de plus pour le reste. Docsbook mémorise si vous l'avez laissée ouverte la prochaine fois que vous revenez. Le + qui crée une nouvelle liste à partir d'un filtre vide se trouve à la fois sur cette ligne et sous forme de carte dans la galerie.

Sept flux sont intégrés, afin que vous ayez quelque chose à ouvrir lors de votre première visite avant même d'avoir enregistré quoi que ce soit : Événements des lecteurs (tout ce que les personnes consultant vos documents ont fait — pages lues, recherches effectuées, questions posées à l'IA, commentaires laissés), Traductions (chaque langue générée, obsolète ou encore nécessaire), Événements de langue (les langues dans lesquelles les lecteurs basculent les documents), Événements de chat (questions posées à l'assistant IA, cas où il n'a pas trouvé de réponse, réponses ayant reçu un pouce vers le bas), Commentaires des lecteurs (pouces vers le bas et commentaires, sur une page ou une réponse), Appels MCP (chaque appel facturé effectué par un agent) et Tous les événements — tout, sans filtre, en dernier dans la liste puisqu'il s'agit de celui auquel vous recourez lorsque aucun des flux nommés ne convient. Événements des lecteurs, Événements de langue et Appels MCP sont des flux à consulter plutôt que des flux auxquels s'abonner, car aucun de leurs événements ne peut être associé à une alerte ; les quatre autres correspondent exactement à ce vers quoi vous dirigeriez un système de notification. Les sept sont des filtres de départ plutôt que des listes enregistrées : ils ne peuvent donc pas être supprimés et rien ne peut leur être associé directement — affinez-en un, puis Enregistrer comme liste le transforme en un flux qui vous appartient, lequel apparaît sur sa propre ligne et constitue la forme à laquelle une alerte peut être associée.

Lecture du flux#

Le flux est organisé en sections par jour, et chaque élément tient sur une ligne : l’avatar du lecteur lorsqu’un lecteur a déclenché l’événement (un événement de planification, d’utilisation ou MCP ne peut être attribué à personne), une tuile colorée indiquant son type, le nom de l’événement, le résumé sur une ligne et sa destination. Le statut, le type d’événement et la destination s’affichent sous forme de petits glyphes, avec le libellé accessible en un clic dans une fenêtre contextuelle, afin que l’ensemble tienne sur une ligne. Les heures sont indiquées au format horaire, puisque le jour est déjà nommé par la section ci-dessus. Cliquer sur une ligne la déploie sur place pour afficher l’événement complet — chaque tentative de livraison avec sa réponse, le rejeu et la charge utile brute. Un événement possède un statut unique, calculé à partir de ses livraisons, le résultat le plus défavorable l’emportant :

Appels d’outils MCP dans le flux#

Le flux affiche également chaque appel d’outil MCP effectué par un agent sur cet espace de travail, ainsi que les événements envoyés par votre documentation. Une ligne par appel : l’outil appelé, s’il a fonctionné, combien de temps il a pris et ce qu’il a coûté au tarif catalogue indiqué sur la grille tarifaire MCP. Les appels échoués sont signalés comme tels. Les appels qui ne concernaient aucun projet en particulier — décrire le serveur, répertorier vos projets, en créer un — sont associés à votre compte plutôt qu’à un projet et n’apparaissent donc dans le flux d’aucun projet.

Ils sont affichés par défaut ; il n’y a rien à activer. Dans le sélecteur Ajouter un événement, ils se trouvent dans leur propre section Appels MCP, filtrés par la classe de facturation de l’appel — mcp.read, mcp.write, mcp.query, mcp.egress, mcp.generate, mcp.agent — plutôt que par le nom de l’outil, qui est l’axe qui vous coûte de l’argent et qui continue de fonctionner à mesure que de nouveaux outils sont déployés. Le nom de l’outil lui-même figure sur chaque ligne et dans chaque charge utile ; il suffit donc d’effectuer une recherche dans la charge utile pour filtrer sur un outil donné. Les appels gratuits (get_info, find_skill, find_widget et le reste de la découverte) ne sont jamais comptabilisés et ne laissent donc aucune ligne.

Un appel d’outil n’a jamais été transféré où que ce soit ; il apparaît donc comme non envoyé et, comme l’activité des lecteurs, il disparaît dès que vous filtrez par destination ou par état de livraison. L’épinglage d’un visiteur le fait également disparaître : un agent détenant un jeton ne fait pas partie de vos lecteurs, et compter ses appels comme la navigation de quelqu’un serait incorrect.

Restreindre le flux#

Filtrez le flux par type d’événement, statut, destination, visiteur, objectif atteint ou texte libre correspondant n’importe où dans la charge utile — une seule ligne de barre d’outils au-dessus du flux, sans titre au-dessus. Chacune des cinq premières facettes est un bouton icône : survolez-le ou placez-y le focus pour voir son nom ; une fois défini, il se remplit avec la valeur elle-même, et cliquer sur cette valeur permet de la modifier à nouveau. Le texte libre dispose de sa propre boîte de recherche toujours visible à la fin de cette ligne, plutôt que d’être une facette que vous devez d’abord ouvrir. Un filtre de visiteur est accessible en un clic depuis Analytics : ouvrez-y un lecteur et accédez directement à tout ce qu’il a fait — en un clic depuis l’avatar d’une ligne dans le flux lui-même, ou en saisissant manuellement un identifiant collé. Épingler un lecteur élargit ce que le flux recherche : en plus des événements envoyés par vos documents, il récupère l’activité de ce lecteur sur le site — les pages qu’il a lues, ce qu’il a recherché, ce qu’il a demandé — ainsi, un flux épinglé regroupe tout ce que ce lecteur a fait, et pas seulement les éléments susceptibles d’avoir déclenché une alerte. Il affiche également une carte au-dessus du flux indiquant qui est ce lecteur : depuis quel endroit il lit, sur quel appareil, avec quel système et quel navigateur, dans quelle langue il lit, la page à laquelle il revient régulièrement, le temps total qu’il a passé à lire votre documentation, les objectifs qu’il a atteints et ce qu’il vaut aujourd’hui, ainsi que ce qu’il pourrait encore rapporter. La carte est réservée à un seul lecteur épinglé, car un filtre d’objectif correspond à un groupe, et un pays et un navigateur moyens pour un groupe ne décrivent personne. Enregistrer un filtre le transforme en liste d’événements — ainsi, restreindre le flux et définir ce qui doit déclencher une notification sont un seul et même geste. Les signaux de test apparaissent dans le flux comme n’importe quel autre événement ; une nouvelle tentative apparaît sous l’événement auquel elle appartient. Exporter télécharge exactement ce que vous consultez, avec les filtres appliqués et sans limite temporelle, au format CSV, JSON ou NDJSON — sans limite, car le flux lui-même ne comporte aucune plage de temps : il est en direct, et un fichier plus restreint que la vue qu’il copie est pire que l’absence de fichier. Il se trouve à la fin de cette même ligne de barre d’outils, à côté de Configurer Prompt et de Configurer une alerte — les trois commandes qui agissent sur l’ensemble de la vue plutôt que sur un seul événement.

Exécuter un prompt sur un flux#

Une alerte transmet les événements d’un flux à une personne. Configurer le prompt, juste à côté sur la même ligne, les transmet à votre assistant à la place : choisissez un prompt et il s’exécute automatiquement chaque fois que quelque chose arrive dans ce flux, sans que personne ne le surveille. Le bouton affiche un compteur, de sorte qu’un flux contenant quelque chose ne ressemble jamais à un flux vide, et chaque prompt activé reçoit une pastille à côté des pastilles de destination — pleine pendant son exécution, creuse lorsqu’il est en pause, avec sa dernière exécution dans l’infobulle.

Cliquer sur une pastille n’ouvre pas ses paramètres. Cela ouvre la conversation que le prompt a eue : la transcription de ce qu’il a réellement fait la dernière fois que ce flux a évolué, dans le groupe Déclencheurs de l’assistant. C’est la seule chose qui puisse vous indiquer qu’un prompt fonctionne plutôt que d’être simplement activé.

Ce qui surveille un flux surveille un flux enregistré, de sorte qu’une vue que vous avez restreinte mais pas encore enregistrée le signale et pointe vers Enregistrer comme liste. La même activation est disponible depuis l’autre côté — le panneau Selon une planification ou un événement sur la propre page d’un outil MCP répertorie vos flux au-dessus des événements individuels — et la suppression d’un flux désactive ce qui le surveillait au lieu de supprimer l’appel activé.

Ce que tout cela a coûté#

Chaque ligne du flux comporte un prix, et une ligne à la fois ne constitue pas un total que l'on puisse additionner. Voir l'utilisation sur la carte de solde dans la barre latérale remplace le flux par la somme : à quoi l'argent de ce projet a été consacré sur une période, du plus coûteux au moins coûteux, en trois sections. Cette option ne se trouve pas dans la barre d'outils du flux lui-même, car le chiffre concerne l'ensemble du projet et non le flux que vous consultez.

Les deux premières sont facturées : cet argent a été déduit du solde du projet. La troisième ne l'est pas — les événements sont tarifés afin que le trafic ne soit pas invisible, mais rien n'est déduit pour eux. Les deux totaux sont donc affichés sous la forme de deux chiffres associés à deux termes différents, et chaque section comporte un badge charged ou not charged, car un seul chiffre couvrant les trois constituerait une facture correspondant à de l'argent que personne n'a prélevé.

Choisissez une période de 24 heures, 7 jours ou 30 jours. Il n'y a pas de période plus longue, car il n'y a rien de plus ancien à consulter : les analyses des lecteurs sont conservées pendant 30 jours et le registre d'IA est élagué en conséquence, si bien qu'un bouton de 90 jours fournirait des données sur 30 jours sous un intitulé incorrect.

Exporter propose ici le détail lui-même au format CSV — une ligne par modèle, outil ou type d'événement, avec son nombre et son coût sous la forme d'un nombre simple que vous pouvez additionner, ainsi qu'une colonne indiquant si cette ligne a été facturée — et les événements bruts qui le sous-tendent, limités à la période que vous consultez.

Le même écran est celui qu'ouvre Voir l'utilisation depuis l'avis de solde de la barre latérale — la carte qui avertit lorsque le solde de ce projet devient faible. Le rechargement s'effectue dans le bloc Solde du menu du compte : l'un indique ce qu'il reste, l'autre indique à quoi cela a été consacré.

Notificateurs : où vont les événements#

Un notificateur est une destination — un canal, son URL et ses identifiants — et il existe indépendamment des événements qu'il transporte. Vous le créez une fois — Configurer une alerte dans la ligne de titre, ou Nouveau notificateur en bas de Ajouter un notificateur — puis vous le cochez dans autant de listes d'événements qu'il doit desservir. Un canal Slack alimenté par trois listes correspond à un seul notificateur, avec un seul secret de signature, mis en pause ou supprimé à un seul endroit.

Les notificateurs qui s'exécutent déjà sur la liste que vous consultez se trouvent à côté des puces de filtre, sous forme de leurs propres puces libellées — chacune avec le véritable symbole de son canal, son nom et paused lorsqu'elle est désactivée. En cliquant sur l'une d'elles, vous ouvrez ce notificateur et pouvez voir vers quoi une liste achemine ses événements et le modifier, sans quitter le flux. Pour accéder à un notificateur qui s'exécute sur une autre liste — ou sur aucune pour l'instant, comme c'est le cas de tout nouveau notificateur — utilisez le menu Ajouter un notificateur, où chaque ligne comporte un contrôle de modification à côté de sa case à cocher.

Décochez une liste et le notificateur cesse de s'y exécuter ; décochez la dernière et la destination reste en place, attachée à rien et ne livrant rien jusqu'à ce que vous l'affectiez à nouveau. La suppression d'une liste d'événements produit le même effet pour tout ce qui s'y exécutait — un abonnement n'est jamais élargi par la perte de sa liste.

Seules les listes enregistrées peuvent être desservies : les flux intégrés, notamment Tous les événements, sont des filtres plutôt que des listes ; enregistrez donc d'abord celui que vous voulez comme votre propre flux.

Catalogue des événements#

Un espace de travail Docsbook émet 18 événements typés. Chaque ligne ci-dessous nomme l’événement exactement comme il apparaît dans l’en-tête X-Docsbook-Event et dans le champ event du corps, avec les champs portés par son objet data.

Trois des dix-huit événements sont marqués comme avancés — traffic.spike, traffic.drop et mcp.tool_called. Chacun est dérivé d’une référence ou d’une activité mesurée, plutôt que d’être déclenché directement par une action.

Enregistrer un webhook#

Via 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"}'

La réponse inclut exactement une fois secret — stockez-le.

event_type accepte l’une ou l’autre des formes d’un nom d’événement : la forme avec des points utilisée partout sur cette page (content.indexed) ou la forme avec des traits de soulignement (content_indexed). Les deux enregistrent le même abonnement.

En-tête Authorization facultatif#

Certains récepteurs (par exemple une URL de déclenchement de routine Claude Code) exigent leur propre jeton bearer à chaque requête, indépendamment de la vérification de la signature HMAC. Transmettez auth_header lors de la création du webhook et Docsbook l'enverra tel quel en tant que Authorization à chaque livraison :

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-..."}'

Si la valeur ne contient pas d'espace, elle est envoyée sous la forme Bearer <value> ; si elle contient déjà un schéma (par ex. Bearer sk-...), elle est envoyée telle quelle.

Via MCP#

Chaque événement dispose d’un outil MCP dédié, afin qu’un agent d’IA puisse s’abonner à un flux de notifications spécifique sans avoir à sélectionner de chaînes :

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")

Autres outils MCP, avec la classe de facturation sous laquelle chaque appel est comptabilisé :

Points de terminaison REST#

• GET /api/webhooks?workspace_id=X — lister
• POST /api/webhooks — créer
• PATCH /api/webhooks/:id — renommer, mettre en pause/reprendre ou rediriger vers une autre liste d’événements
• POST /api/webhooks/:id/attach — { "list_id": N }, servir une liste supplémentaire depuis la même destination (même URL, même secret)
• DELETE /api/webhooks/:id — supprimer
• POST /api/webhooks/:id/test — tester le ping
• GET /api/webhooks/:id/deliveries — livraisons récentes
• POST /api/webhook-deliveries/:id/replay — remettre en file d’attente une livraison existante

Sémantique des nouvelles tentatives et des échecs#

• Le worker s’exécute toutes les minutes via le cron Vercel.
• Une livraison est tentée jusqu’à 3 fois.
• Le délai d’attente est appliqué à partir de created_at de la ligne : 1 s, 10 s, 60 s.
• Après le 3e échec → status = "failed". Utilisez replay_webhook_delivery pour réessayer.
• Le code de réponse et le corps (tronqué) sont enregistrés pour chaque ligne de livraison.

Ressources associées#

• Référence des outils MCP — les outils register_webhook_<event> et tous les autres outils du serveur
• Vue d’ensemble du serveur MCP — la connexion d’un client et la grille tarifaire appliquée aux appels du flux
• Référence des événements suivis — les actions des lecteurs à l’origine de plusieurs de ces événements
• Vue d’ensemble des analyses — consulter la même activité sous forme de rapport plutôt que de flux