Notion Developer Platform 3.5 : guide complet

La Notion Developer Platform 3.5, annoncée le 13 mai 2026, transforme Notion en hub d’orchestration d’agents IA. Pour la première fois, une équipe peut faire tourner du code personnalisé, intégrer Claude Code ou Codex comme agents natifs, et déclencher des workflows depuis n’importe quelle application — sans gérer la moindre infrastructure externe.

Depuis le lancement, plus d’un million d’agents personnalisés ont déjà été construits par des équipes dans le monde. La fenêtre pour expérimenter gratuitement reste ouverte jusqu’au 11 août 2026.

Les 5 briques de la Developer Platform 3.5

5 composants, 2 niveaux d’accès : bêta publique immédiate (CLI, Workers, Webhooks) et alpha privée sur liste d’attente (External Agents API, Agent SDK).

La plateforme se décompose en cinq composants distincts, chacun répondant à un besoin précis. Vous n’êtes pas obligé d’utiliser les cinq : certaines équipes démarreront avec le CLI et les webhooks, d’autres iront directement vers l’External Agents API.

Le CLI et les webhooks sont les deux composants les plus accessibles aujourd’hui. Les External Agents et l’Agent SDK sont en accès anticipé via app.notion.com/developers.

Workers : exécuter du code dans le sandbox Notion

Les Notion Workers existent depuis plusieurs mois en alpha, mais la version 3.5 marque leur passage en bêta publique avec une architecture clarifiée. Un Worker est une fonction TypeScript qui tourne dans un environnement hébergé par Notion — pas de Lambda, pas de serveur, pas de cron externe à maintenir.

Ce que vous pouvez construire avec un Worker

Trois types de Workers couvrent la majorité des cas d’usage :

Database Sync — un Worker planifié qui tire des données depuis n’importe quelle API vers une base Notion. Synchroniser les tickets Zendesk, les contacts Salesforce, les transactions Stripe ou les données PostgreSQL devient une affaire de quelques dizaines de lignes de TypeScript.

Agent Tools — des fonctions déterministes que vos Custom Agents peuvent appeler. Contrairement aux appels LLM chaînés, ces outils s’exécutent de façon prévisible et consomment moins de tokens. Selon la documentation officielle, ils offrent « une fiabilité et un coût en tokens bien inférieurs à ceux du raisonnement LLM pour les actions répétitives ».

Webhook Triggers — des handlers qui reçoivent des événements HTTP entrants et déclenchent des workflows Notion en réponse (voir la section dédiée ci-dessous).

Déployer votre premier Worker

# Installer le CLI
curl -fsSL https://ntn.dev | bash

# S'authentifier
ntn login

# Créer un nouveau Worker
ntn workers new mon-premier-worker
cd mon-premier-worker

# Déployer
ntn workers deploy

Chaque Worker s’exécute dans un sandbox éphémère (infrastructure Vercel Sandbox, basée sur des microVMs Firecracker) avec son propre noyau et sa propre pile réseau. Les secrets (clés API, tokens) sont injectés via un proxy réseau sans jamais entrer dans l’environnement d’exécution.

Point important : la gratuité des Workers prend fin le 11 août 2026. À partir de cette date, chaque exécution consomme des Notion Credits. Je recommande de journaliser vos invocations dès maintenant pour anticiper les coûts de production.

CLI ntn : piloter Notion depuis le terminal

Le CLI est le fil conducteur de toute la Developer Platform. Il s’installe en une ligne, fonctionne sur macOS et Linux (Windows via WSL), et est disponible sur tous les plans Notion, y compris le plan gratuit.

Ce que le CLI permet

Au-delà du déploiement de Workers, ntn ouvre un accès programmatique complet à votre workspace :

# Appel direct à l'API Notion
ntn api GET /v1/users/me

# Lister les webhooks actifs
ntn workers webhooks list

# Inspecter les exécutions
ntn workers runs list
ntn workers runs logs <run-id>

Le CLI supporte trois modes d’authentification selon votre contexte : session interactive (ntn login), token d’accès personnel (PAT) pour les scripts CI/CD, et OAuth 2.0 pour les intégrations distribuées. Les PAT se créent depuis le portail développeur.

CLI et agents de code

Un aspect peu documenté mérite d’être souligné : le CLI est explicitement conçu pour être utilisé par des agents de code — Claude Code, Codex, Cursor — et pas seulement par des humains. Un agent peut s’authentifier, déployer un Worker et interroger des données Notion de façon autonome dans un pipeline CI/CD, sans interface graphique.

External Agents API : intégrer Claude Code, Cursor et Codex

Notion comme hub d’orchestration : 4 agents natifs intégrés au lancement, spécification ouverte pour les agents custom. MCP 91 % plus efficace en tokens.

L’External Agents API est le composant le plus attendu de la Developer Platform 3.5. Il permet à des agents tiers — Claude Code, Codex, Cursor, Decagon, ou un agent que vous avez développé — d’opérer dans votre workspace Notion comme des participants à part entière.

Ce que « participant à part entière » signifie concrètement

Avec l’API traditionnelle, un agent externe interagit avec Notion via des appels REST anonymes. Avec l’External Agents API, l’agent :

• Dispose de sa propre identité et apparaît dans les @mentions
• Peut être assigné à des éléments de base de données (tickets, tâches, issues)
• Peut chatter dans des pages et voir l’historique de conversation
• S’intègre dans les workflows d’approbation des Custom Agents

Un scénario typique : une issue GitHub entre dans Notion via un webhook, est automatiquement assignée à Claude Code, qui analyse le contexte dans les pages liées, propose un correctif dans la page de l’issue, et attend l’approbation de l’équipe avant d’ouvrir une PR.

Quatre agents intégrés nativement

Pour les équipes qui utilisent d’autres agents, la spécification de l’API est ouverte et documentée sur developers.notion.com.

Accès actuel : l’External Agents API est en alpha privée, accessible sur liste d’attente. En attendant, vous pouvez déjà connecter Claude Code à Notion via le serveur MCP officiel, disponible sans délai d’attente. Le MCP a été amélioré avec la version 3.5 : la création et la mise à jour de bases de données sont désormais 91 % plus efficaces en tokens qu’auparavant (selon Notion, mai 2026).

Agent SDK : embarquer Notion dans vos outils

L’Agent SDK fonctionne dans la direction inverse de l’External Agents API. Plutôt que de faire entrer un agent externe dans Notion, il permet d’embarquer un agent Notion dans un autre outil : un CRM, MS Teams, Discord, ou une application maison.

Cas d’usage typiques

CRM → Notion : un commercial ferme une opportunité dans HubSpot. L’Agent SDK déclenche automatiquement un agent Notion qui crée la fiche client, génère le plan d’onboarding à partir des notes de vente, et envoie un résumé dans le canal Slack de l’équipe.

Support → Notion : un ticket de priorité haute arrive dans Zendesk. L’SDK déclenche l’agent Notion pour rassembler le contexte client depuis les bases de données, rédiger une réponse initiale basée sur la base de connaissances, et alerter l’équipe produit si un bug est détecté.

L’Agent SDK est actuellement en alpha privée, accessible sur liste d’attente via app.notion.com/developers. Il n’est pas encore adapté aux workflows en production — Notion le précise explicitement dans sa documentation.

Webhooks entrants : déclencher vos workflows depuis l’extérieur

Les webhooks entrants comblent une lacune importante de l’écosystème Notion : jusqu’à présent, les automations et les agents ne pouvaient être déclenchés que depuis l’intérieur du workspace. Désormais, n’importe quelle application HTTP peut initier un workflow Notion.

Configuration en TypeScript

worker.webhook("onStripeEvent", {
  title: "Stripe Payment Webhook",
  execute: async (events) => {
    for (const event of events) {
      // Vérification de la signature
      const sig = event.headers["stripe-signature"];
      // Traitement et écriture dans Notion via context.notion
    }
  },
});

Après déploiement via ntn workers deploy, Notion génère une URL unique récupérable avec ntn workers webhooks list. Cette URL reçoit les événements POST de n’importe quel service : GitHub, Stripe, Zendesk, PagerDuty, ou votre propre backend.

Sécurité et gestion des erreurs

Deux règles essentielles pour une mise en production sereine :

Vérification de signature : la plupart des services signent leurs webhooks avec un secret partagé (HMAC-SHA256 pour GitHub, par exemple). Stockez ce secret comme variable d’environnement Worker et vérifiez chaque requête via event.rawBody et event.headers. Utilisez une comparaison à temps constant pour éviter les attaques temporelles.

Gestion des échecs : en cas d’erreur de vérification de signature, levez une WebhookVerificationError — Notion ne retentera pas la requête. Pour les autres erreurs, Notion retentera automatiquement. Après plusieurs échecs de vérification consécutifs, le webhook est bloqué automatiquement ; un redéploiement du Worker réinitialise le compteur.

MCP amélioré et API Markdown

Deux améliorations complémentaires accompagnent la Developer Platform 3.5 et méritent d’être mentionnées.

MCP 91 % plus efficace

Le serveur MCP officiel de Notion a été entièrement restructuré. La création et la mise à jour de bases de données y sont désormais 91 % plus efficaces en tokens qu’avec la version précédente, ce qui réduit sensiblement les coûts d’utilisation dans les pipelines d’agents. Pour les équipes qui utilisent déjà Claude Code ou Cursor avec le MCP Notion, la mise à jour est transparente.

API Markdown pour lire et écrire des pages

La nouvelle API Markdown permet de lire et d’écrire des pages Notion directement en Markdown, sans avoir à manipuler les blocs JSON natifs de l’API. Pour les agents de code, c’est un changement de paradigme : ils travaillent dans un format qu’ils maîtrisent nativement, sans couche de conversion intermédiaire.

Cette API s’ajoute à l’API Notion existante sans la remplacer — les deux coexistent et répondent à des besoins différents.

Comment démarrer aujourd’hui : par où commencer

Selon votre profil et vos priorités, voici l’ordre d’exploration que je recommande.

Si vous voulez commencer maintenant (sans liste d’attente)

1. Installez le CLI : curl -fsSL https://ntn.dev | bash — disponible sur tous les plans
2. Activez le MCP Notion dans Claude Code ou Cursor — 91 % plus efficace, disponible immédiatement
3. Déployez un Worker simple — commencez par un Database Sync depuis une API que vous utilisez déjà
4. Configurez un webhook entrant — connectez GitHub ou Stripe à votre workspace

Si vous gérez une équipe technique (plan Business ou Enterprise)

5. Rejoignez la liste d’attente External Agents API sur app.notion.com/developers
6. Rejoignez la liste d’attente Agent SDK si vous avez des outils internes à connecter
7. Journalisez vos invocations Workers dès maintenant pour anticiper les coûts post-11 août

La configuration des Custom Agents Notion reste le point d’entrée le plus simple si vous ne voulez pas écrire de code. Les Workers et l’External Agents API sont des extensions pour les équipes qui ont besoin de plus de contrôle et de flexibilité.

Ce qui change pour les power users

Avant : automations cloisonnées et dépendantes d’outils tiers. Après : orchestration native d’agents, code TypeScript hébergé et déclenchement depuis n’importe quelle app HTTP.

La Developer Platform 3.5 déplace Notion d’un outil de productivité vers une couche d’orchestration d’agents. Les implications concrètes pour une équipe technique :

Avant la 3.5 : les automatisations Notion s’arrêtaient aux règles déterministes (si X, alors Y) ou dépendaient d’outils tiers comme Make ou Zapier pour les connexions externes. Les agents IA étaient cloisonnés dans l’interface Notion.

Après la 3.5 : un même workspace Notion peut recevoir des événements de systèmes externes (via webhooks), exécuter du code TypeScript (via Workers), orchestrer des agents internes et externes (via Custom Agents + External Agents API), et déclencher des actions dans d’autres outils (via Agent SDK).

Pour les automations Notion existantes, rien ne change — elles continuent de fonctionner. Les Workers et les agents sont des couches supplémentaires, pas des remplacements.

Mon avis après analyse

La Developer Platform 3.5 est l’une des annonces les plus techniques de Notion depuis l’ouverture de l’API publique en 2021. Le positionnement est clair : Notion veut devenir le workspace central autour duquel gravitent les agents IA, et non pas un outil parmi d’autres dans une stack d’automatisation.

Ce qui m’a surpris positivement : le CLI est disponible sur tous les plans, y compris le plan gratuit. C’est un choix délibéré pour attirer les développeurs indépendants avant de les convertir vers les plans Business. L’accès graduel (bêta publique / alpha privée) est bien géré et évite de mettre des fonctionnalités instables entre les mains de toutes les équipes.

Ce qu’il faut surveiller : la tarification des Workers post-11 août reste imprécise dans ses détails. « 10 dollars pour 1 000 crédits » partagés avec les Custom Agents peut devenir coûteux si vous avez des Workers à haute fréquence d’exécution. Anticipez cette transition dès maintenant en surveillant vos invocations.

La fenêtre de gratuité totale — CLI + Workers + webhooks — prend fin dans moins de 70 jours. C’est le bon moment pour expérimenter.