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
- Ouvrez Réglages, API et intégrations, puis Clés d’API, et cliquez sur Nouvelle clé.
- 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.
- 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)
- Ouvrez Réglages, API et intégrations, puis Nouveau webhook.
- Donnez une adresse https publique ; les adresses privées et locales sont refusées.
- 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-iddes 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/mcpLa 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