Aide · 15 min

L’API, les webhooks et le serveur MCP

Pour un développeur : les clés, les routes, les webhooks signés et le serveur MCP.

Les clés

  1. Ouvrez Réglages, API et intégrations, puis Clés d’API, et cliquez sur Nouvelle clé.
  2. Choisissez Lecture seule ou Lecture et écriture. Une clé agit avec les droits du membre qui l’a créée ; une clé en lecture seule ne modifie jamais les données.
  3. Copiez-la tout de suite : elle ne sera plus affichée. Révoquez-la au même endroit quand vous n’en avez plus besoin.

Appeler l’API

Toutes les routes commencent par https://app.bondossier.com/api/v1/ et prennent la clé dans l’en-tête Authorization. Une clé peut faire 240 requêtes par minute ; au-delà, la réponse 429 dit combien de secondes attendre (en-tête Retry-After).

curl https://app.bondossier.com/api/v1/self \
  -H "Authorization: Bearer <votre-clé>"

Les routes

GET /selfL’espace et la clé utilisés

GET /objectsLes tables de l’espace

GET /objects/{table}Une table et ses champs

POST /objects/{table}/records/queryChercher des fiches avec des filtres

POST /objects/{table}/recordsCréer une fiche

PUT /objects/{table}/records?matching_attribute={champ}Créer ou mettre à jour selon un champ (par exemple l’email)

GET · PATCH · DELETE /records/{id}Lire, modifier ou supprimer une fiche

GET · POST /records/{id}/notesLes notes d’une fiche

GET · POST /tasksLister ou créer des tâches

GET /search?q=…Rechercher dans l’espace

GET /listsLes listes

POST /lists/{liste}/entries/queryChercher dans une liste

POST /lists/{liste}/entriesAjouter une fiche à une liste

PATCH · DELETE /entries/{id}Modifier ou retirer une entrée

POST /importsImporter jusqu’à 5 000 lignes en un envoi (table, rows, match_by, create_missing), en arrière-plan

GET /imports/{id}Où en est un import

POST /imports/{id}/undoAnnuler tout un import

S’abonner aux événements (webhooks)

  1. Ouvrez Réglages, API et intégrations, puis Nouveau webhook.
  2. Donnez une adresse https publique ; les adresses privées et locales sont refusées.
  3. Choisissez les événements et le format (JSON, ou un message prêt pour Slack).

Événements : record.created, record.updated, record.archived, record.restored, record.deleted, entry.created, entry.updated, entry.deleted, note.created, task.created, task.completed, comment.created, message.received, agent.decision_waiting, agent.blocked. Un envoi ne contient que ce que la personne qui a créé le webhook peut lire. Sans réponse, il est renvoyé avec des délais croissants pendant environ un jour ; une réponse 410 arrête le webhook.

Vérifier la signature

Chaque envoi porte l’en-tête x-webhook-signature: t=<horodatage>,v1=<signature>. L’horodatage est en secondes. La signature est un HMAC-SHA256, encodé en base64url, de <horodatage>. suivi du corps reçu, octet pour octet, avec le secret du webhook.

  • Lisez le corps brut, avant tout JSON.parse : un espace en plus ou en moins change la signature.
  • Refusez un en-tête mal formé, une signature fausse, un horodatage de plus de 5 minutes ou situé dans le futur.
  • Comparez les signatures sans fuite de temps (timingSafeEqual).
  • Gardez l’en-tête x-webhook-id des envois déjà traités : après une reprise, le même événement peut arriver deux fois.
import {createHmac, timingSafeEqual} from 'node:crypto';

// header : la valeur de l’en-tête x-webhook-signature.
// rawBody : le corps reçu, octet pour octet (un Buffer), avant tout JSON.parse.
export function verifyWebhook(header, rawBody, secret, {now = Date.now(), maxAgeSeconds = 300, maxAheadSeconds = 60} = {}) {
  if (typeof header !== 'string' || !Buffer.isBuffer(rawBody) || typeof secret !== 'string' || secret === '') return false;
  const parts = /^t=([0-9]{1,12}),v1=([A-Za-z0-9_-]{43})$/.exec(header);
  if (!parts) return false;
  const age = Math.floor(now / 1000) - Number(parts[1]);
  if (age > maxAgeSeconds || age < -maxAheadSeconds) return false;
  const received = Buffer.from(parts[2], 'base64url');
  if (received.length !== 32 || received.toString('base64url') !== parts[2]) return false;
  const expected = createHmac('sha256', secret).update(parts[1] + '.').update(rawBody).digest();
  return timingSafeEqual(received, expected);
}

Le serveur MCP

L’adresse est https://app.bondossier.com/mcp. Dans Claude, ChatGPT ou Gemini CLI, ajoutez-la comme connecteur, connectez-vous et choisissez l’espace : l’assistant agit avec vos droits. Pour un outil en ligne de commande, une clé d’API fonctionne aussi. Les commandes exactes sont dans Réglages, Brancher votre assistant IA. Pour ne donner à un assistant que certains projets, créez-lui un accès dans Mes accès agents ; vous pouvez le couper à tout moment.

claude mcp add --transport http bondossier --scope user https://app.bondossier.com/mcp

La disponibilité et les menus dépendent de l’assistant et de son abonnement.

Recevoir des fiches sans clé

Le formulaire de votre site n’a pas besoin de clé : il passe par une automatisation. Le pas à pas →

Pour votre équipe

Essayez BonDossier
avec votre équipe.

Gratuit pour une personne. Essai de 30 jours avec les agents.

Dès 19,99 €/mois