Connecteurs et webhook

Recevoir des éléments d'une source externe (formulaire, script, raccourci) et en faire des nœuds.

Un connecteur fait entrer dans Second Brain les éléments d’une source externe : un formulaire, un script, un raccourci iOS, Home Assistant ou n8n. Le premier genre est le webhook : la source envoie un JSON, et le nœud correspondant est créé, ou mis à jour s’il existe déjà. Chaque connecteur est un fichier de config/connectors/ (voir la référence).

Envoyer un élément

curl -X POST https://second-brain.example/api/connectors/capture/webhook \
  -H "Authorization: Bearer $SB_WEBHOOK_CAPTURE" \
  -H "Content-Type: application/json" \
  -d '{"id": "42", "titre": "Rappeler le garage", "texte": "Pneus hiver", "tags": ["voiture"]}'

Jeton. Il est lu dans la variable d’environnement que nomme le connecteur (secret:), ici SB_WEBHOOK_CAPTURE. Sans cette variable, le connecteur est inactif et répond 503. Un mauvais jeton donne 401.
Session. Aucune n’est nécessaire : c’est le seul chemin de l’API ouvert ainsi, et il n’écrit qu’à travers ce connecteur.
Réponse. { "result": "created", "nodeId": "…" }. Le résultat vaut created, updated, unchanged, conflict, deleted ou ignored.
Refus. Une charge invalide est refusée (400), sans rien écrire. C’est le cas d’un identifiant ou d’un titre absent, d’une valeur hors liste, d’une date illisible, ou d’une charge de plus de 256 Ko.

Un élément, un nœud

Chaque nœud reçu porte l’aspect Source externe : la source, l’identifiant chez elle, le lien, la version et la date de la dernière synchro. Un même identifiant met donc à jour le même nœud.

Si la version reçue est la même que la dernière (etag), rien n’est écrit. Si le nœud est dans la corbeille, une nouvelle réception crée un nouveau nœud.

Conflits : la dernière modification gagne

Si vous avez modifié le nœud depuis la dernière synchro, la date de modification envoyée par la source (updatedAt) départage les deux versions :

la source est plus récente : sa version s’applique, et votre version reste dans l’historique de la fiche (avant/après) ;
votre modification est plus récente : elle est gardée, et l’historique note « version de la source écartée », avec la version reçue complète.

Sans date envoyée par la source, l’heure de réception fait foi : la version reçue s’applique.

Suppression à la source

Une charge "supprime": true ne supprime rien. Le champ « Supprimé à la source le » est renseigné, et le nœud garde son contenu et ses liens. Une vue peut l’écarter avec externe.supprimeALaSource == null. Si l’élément revient, la marque est levée.

État des connecteurs

La page Définitions liste les connecteurs avec :

leur état (actif, ou inactif et pourquoi) ;
la dernière réception et son résultat ;
les compteurs (créés, mis à jour, conflits, supprimés, refusés) ;
la dernière erreur.

L’historique de chaque fiche montre les événements « reçu de la source », « mis à jour depuis la source », « supprimé à la source ». Leur auteur est connecteur:<nom>.