Notion

Vos pages et vos bases de données Notion — pour ouvrir un dossier depuis un mail, y classer les pièces jointes et y écrire le suivi.

Une connexion Notion permet au nœud Notion de travailler avec vos pages et vos bases de données : ouvrir un dossier depuis un e-mail, y classer les pièces jointes, y écrire le suivi, commenter, chercher. La même connexion alimente deux déclencheurs : Entrée Notion modifiée, qui interroge une base à intervalle régulier, et Notion — événement, qui reçoit les webhooks Notion.

La connexion porte un jeton d’intégration Notion. Il est chiffré au repos, appliqué par le serveur au moment de l’appel, et n’apparaît jamais dans un workflow. Chaque appel part avec la version d’API Notion figée par le produit (Notion-Version: 2026-03-11) ; elle ne se change pas par connexion.

En bref

• Identifiant : notion
• Famille : Service
• Configurée par : Un membre (personnelle) ou un administrateur (partagée avec l’organisation)
• Authentification : Clé d’API ou jeton
• Type de credential : service:notion
• Documentation officielle de l’API : https://developers.notion.com/reference/intro
• URL de base de l’API : https://api.notion.com
• Limite de débit appliquée par Mankomail : 180 requêtes par minute et par connexion ; jusqu’à 4 tentatives sur un 429 ou un 5xx
• Signature des webhooks : en-tête X-Notion-Signature, HMAC-SHA256 du corps brut
• Test de connexion : Oui

Pas à pas

Les mêmes étapes s’affichent dans le formulaire de connexion de l’application.

1. Ouvrez https://www.notion.so/profile/integrations, puis « New integration » (ou « New token »).
2. Donnez-lui un nom, choisissez l’espace de travail, puis validez par « Save » — le jeton (ntn_…) ne s’affiche qu’une fois.
3. Dans l’onglet « Capabilities », activez : Read content, Update content, Insert content, Read comments, Insert comments, et « User information with email ».
4. Collez le jeton ci-dessous, puis — étape indispensable — PARTAGEZ vos pages : dans Notion, ouvrez la page ou la base racine → menu « ··· » → « Connections » → « Add connections » → votre intégration. Le partage est hérité par les sous-pages.
5. Pour un webhook Notion : publiez le workflow, copiez l’URL affichée dans la fiche du déclencheur « Notion — événement », et créez la souscription dans le portail développeur de Notion. Notion envoie alors à cette URL un jeton de vérification, que nous rangeons dans cette connexion : rouvrez-la, cliquez « Afficher le jeton reçu », copiez-le et collez-le dans Notion (« Verify »).

Champs de la connexion

Champ	Nature	Requis	Remarques
Jeton d’intégration (token)	Secret — jamais réaffiché	Oui	Il ne voit que les pages que vous partagez explicitement avec l’intégration. Un jeton personnel (PAT), lui, voit tout ce que vous voyez — à réserver à un compte de service dédié.
Jeton de vérification des webhooks (verificationToken)	Secret — jamais réaffiché	Non	Facultatif, et rempli tout seul : Notion l’envoie à l’URL du déclencheur à la création de la souscription. Il sert ensuite de clé de signature. Videz-le pour en recevoir un nouveau.

Avant de commencer

• Créez l’intégration depuis https://www.notion.so/profile/integrations, dans l’espace de travail que les workflows utiliseront. Vous devez avoir le droit d’y créer des intégrations.
• Une intégration interne ne voit rien tant qu’aucune page ne lui est partagée. C’est la cause n° 1 des listes vides et des erreurs object_not_found. Dans Notion, ouvrez la page ou la base racine → menu ··· → Connections → Add connections → votre intégration. Le partage est hérité par les sous-pages : partagez la page la plus haute qui ait du sens.
• Un jeton personnel (PAT) est aussi accepté. Il voit tout ce que voit son propriétaire, sans partage page par page — réservez-le à un compte de service dédié. Il ne permet pas de lister les membres de l’espace.
• Une relation vers une autre base n’est lisible que si cette autre base est, elle aussi, partagée avec l’intégration ; sinon sa valeur revient vide, sans erreur.

Autorisations

Dans Notion, ce sont les Capabilities de l’intégration. Activez ce dont les nœuds que vous utilisez ont besoin :

Capacité	À quoi elle sert
Read content	Toute lecture : Recherche, Rechercher des entrées, Entrées créées ou modifiées depuis…, Lire le schéma, Lire une page, Lister les blocs, Lire le contenu en Markdown, les listes de l’éditeur, et le déclencheur Entrée Notion modifiée. Obligatoire.
Update content	Mettre à jour les propriétés, Mettre à la corbeille / restaurer.
Insert content	Créer une entrée, Créer une page, Ajouter des blocs, Écrire du contenu en Markdown, Téléverser les pièces jointes.
Read comments	Lister les commentaires. Facultative.
Insert comments	Commenter. Facultative.
User information with email	Lister les personnes avec leur e-mail (pour les propriétés people), et l’affichage du nom de l’espace par le test de connexion. Facultative, mais sans elle la liste des membres échoue.

Une capacité manquante se manifeste par un 403 au moment où le workflow tourne, pas à l’enregistrement de la connexion.

Bases de données et sources de données

Depuis la version d’API Notion 2025-09-03, une base de données est un conteneur qui héberge une ou plusieurs sources de données, et c’est la source qui porte le schéma. Presque tous les endpoints exigent l’identifiant de la source, pas celui de la base ; les deux ne sont pas interchangeables.

L’éditeur s’occupe de la cascade : choisissez la Base de données (le nom que vous voyez dans Notion, son identifiant ou son URL collée), puis la Source de données — qui n’a qu’une entrée dans la quasi-totalité des cas —, puis les propriétés. Les listes de propriétés rendent le nom de la propriété, c’est-à-dire ce que Notion attend dans les filtres, les tris et les écritures.

La recherche Notion est indexée, donc légèrement en retard : une page partagée à l’instant peut ne pas encore apparaître dans une liste. Collez alors son URL ou son identifiant.

Ajouter la connexion

1. Ouvrez Connexions. Dans la section Services tiers, repérez la carte Notion et cliquez sur Connecter.
2. Donnez un Nom à la connexion et choisissez la Portée : Personnelle (vous seul la voyez et l’utilisez) ou Organisation (toute l’organisation l’utilise ; seul un administrateur peut la créer).
3. Collez le Jeton d’intégration (ntn_…). Laissez vide le Jeton de vérification des webhooks, sauf si vous utilisez le déclencheur Notion — événement. Cliquez sur Créer la connexion.
4. Partagez vos pages avec l’intégration dans Notion (voir plus haut).
5. De retour dans la liste, cliquez sur Configurer sur la nouvelle connexion, puis sur Tester la connexion.

Le test se fait en deux temps :

1. GET /v1/users/me valide le jeton et rend le nom de l’espace de travail, affiché dans le résultat. Si la capacité User information est coupée, Notion répond 403 ; le test continue, sans nom.
2. POST /v1/search avec une taille de page de 1 vérifie que quelque chose est partagé avec l’intégration. Si rien ne l’est, le test échoue — le jeton est valide, mais toutes les opérations échoueraient en 404. Le message affiché est « le service a répondu autre chose que ce qu’on attendait » : partagez une page ou une base, puis testez à nouveau.

Dans un nœud, choisissez la connexion dans Connexion Notion, puis la base et la source de données, ou une page. Supprimer est refusé tant qu’un workflow publié utilise la connexion.

Webhooks

Deux déclencheurs réagissent aux changements dans Notion. Les deux livrent leurs données sous data.notion, et aucun n’a de mail porteur.

Par sondage : Entrée Notion modifiée

Entrée Notion modifiée (trigger.notion_changes) ne demande aucune configuration dans Notion. Choisissez la Base de données, la Source de données, Déclencher sur (une entrée créée ou modifiée, une entrée nouvelle, une entrée modifiée seulement) et Vérifier toutes les (minutes).

• Il s’arme à la publication, en partant de « maintenant » : publier ne rejoue jamais l’historique de la base.
• L’intervalle vaut 15 minutes par défaut, accepte de 5 à 1 440, et ne descend jamais sous le plancher de l’instance (INTEGRATION_POLL_MIN_MINUTES, 5 par défaut — voir les variables d’environnement).
• Chaque passage lit au plus une page d’entrées ; chaque entrée donne une exécution. La clé de déduplication dérive de l’entrée et de sa dernière modification : un passage répété ne crée pas de doublon.
• Un échec définitif (jeton révoqué, base qui n’est plus partagée) lève une notification, « Le déclencheur du workflow … est en panne », jusqu’à ce que les passages refonctionnent.

C’est le chemin recommandé : il fonctionne pour tout espace de travail, sans configuration.

Par webhook : Notion — événement

Notion — événement (trigger.notion) reçoit les webhooks de Notion sur l’URL du workflow :

<PUBLIC_BASE_URL>/hooks/wf/<jeton>

• Obtenir l’URL. Le jeton est généré à la première publication du workflow et rendu une seule fois. Vous pouvez en générer un nouveau avec POST /api/v1/workflows/{id}/webhook (voir l’API) : la réponse donne webhook.url, à préfixer par <PUBLIC_BASE_URL>. Une nouvelle URL invalide la précédente.
• S’abonner. Notion n’offre aucune API pour créer une souscription. Dans le portail développeur Notion, ouvrez l’onglet Webhooks de votre intégration, créez une souscription avec l’URL (publique, en HTTPS) et choisissez les événements.
• Jeton de vérification. À la création, Notion envoie une requête unique contenant un verification_token, puis attend que vous le recolliez dans le portail (Verify). Collez la même valeur dans le champ Jeton de vérification des webhooks de la connexion : elle devient la clé de signature.
• Signature. Chaque événement porte X-Notion-Signature: sha256=<hex>, un HMAC-SHA256 du corps brut avec le jeton de vérification pour clé. Mankomail la vérifie avant de créer quoi que ce soit. Une signature absente ou fausse, ou une connexion sans jeton de vérification, reçoit le même 404 qu’une URL inconnue ; la raison n’est écrite que dans les journaux du serveur.
• Filtrage. Notion envoie tous les événements de l’espace de travail sur la même URL. Mankomail lit type dans le corps et ne crée une exécution que pour les Événements cochés sur le déclencheur (par défaut : Propriétés d’une page modifiées) ; rien de coché = tout. Les événements écartés sont acquittés par 202. Base concernée est indicatif : pour ne traiter qu’une base, comparez data.notion.entity.id dans une condition.
• Déduplication. Notion rejoue une livraison jusqu’à huit fois avec le même id d’événement ; Mankomail s’en sert comme clé de déduplication, et un rejeu ne crée pas de seconde exécution.
• Charge utile. Le corps est léger : des identifiants et des métadonnées (data.notion.type, data.notion.entity.id, data.notion.authors), jamais le contenu. Relisez la page avec le nœud Notion si besoin.
• Boucles. Un workflow qui écrit dans Notion déclenche de nouveaux événements. Comparez {{ data.notion.authors[0].id }} à l’identifiant du bot de la connexion (Utilisateur → Lire le compte de la connexion) dans une condition.

WARNING

La requête de vérification envoyée par Notion à la création n’est pas signée. Comme Mankomail refuse les requêtes non signées sur ce déclencheur, elle reçoit un 404 et son jeton n’est pas affiché dans Mankomail. Obtenez le verification_token par un autre moyen avant de le coller dans la connexion, ou utilisez Entrée Notion modifiée, qui ne demande aucune souscription.

Erreurs fréquentes

Message ou code	Cause	Que faire
Test : « le service a répondu autre chose que ce qu’on attendait » (integration.unexpected_response)	Le jeton est valide mais rien n’est partagé avec l’intégration.	Dans Notion, ··· → Connections → Add connections sur une page ou une base racine, puis testez à nouveau.
Test : « la clé est refusée par le service » (integration.unauthorized)	Jeton révoqué, régénéré ou mal copié.	Copiez le jeton actuel depuis les réglages de l’intégration et remplacez-le.
Le test réussit sans nom d’espace	La capacité User information est coupée.	Facultatif : activez-la pour voir le nom et lister les membres.
Listes vides dans l’éditeur	Rien n’est partagé, ou la page vient d’être partagée (la recherche est indexée).	Partagez la page ; collez son URL ou son identifiant en attendant.
integration.not_found (code Notion object_not_found)	La page ou la base n’est pas partagée avec l’intégration, ou un identifiant de base a été donné là où un identifiant de source de données est attendu.	Partagez la page ; choisissez la base puis la Source de données dans l’éditeur.
integration.unauthorized pendant une exécution	401, ou 403 pour une capacité manquante (par exemple Insert comments pour Commenter).	Activez la capacité dans Notion, ou remplacez le jeton.
integration.rejected	400 ou 422 : Notion a refusé le corps (propriété inconnue, valeur inadaptée au type, validation_error).	Vérifiez les noms et types de propriétés au regard du schéma de la source.
integration.rate_limited	429 après les nouvelles tentatives. Mankomail envoie au plus 180 requêtes par minute et par connexion et réessaie jusqu’à 4 fois en respectant Retry-After.	Temporaire : le moteur reprend l’étape plus tard.
integration.unavailable	5xx, 409 (écriture concurrente) ou panne réseau, après rejeu.	Temporaire : le moteur reprend l’étape plus tard.
integration.connection_unusable	La connexion a été supprimée, n’est pas active, est hors de votre portée, ou appartient à un autre service.	Choisissez une connexion valide dans le nœud.
La liste des membres échoue	Le jeton est un PAT, ou User information est coupée.	Utilisez le mode identifiant du champ, ou un jeton d’intégration avec cette capacité.
Les événements webhook ne démarrent jamais le workflow	Workflow non publié, jeton de vérification absent ou faux dans la connexion, événements non cochés, ou souscription pointant vers une ancienne URL.	Publiez, collez le jeton de vérification, relisez Événements, et vérifiez l’URL de la souscription.

Événements de webhook

Les événements proposés par le déclencheur. Un événement ajouté plus tard par le fournisseur reste accepté quand aucun événement n’est coché.

Événement	Libellé
page.created	Page créée
page.properties_updated	Propriétés d’une page modifiées
page.content_updated	Contenu d’une page modifié
page.moved	Page déplacée
page.deleted	Page mise à la corbeille
page.undeleted	Page restaurée
data_source.content_updated	Entrées d’une base modifiées
data_source.schema_updated	Schéma d’une base modifié
comment.created	Commentaire ajouté
comment.updated	Commentaire modifié
comment.deleted	Commentaire supprimé

Nœuds qui utilisent cette connexion

• Notion — événement — trigger.notion
• Entrée Notion modifiée — trigger.notion_changes
• Notion — notion.api