Valider les payloads JSON entrants dans n8n : schema, Ajv et bonnes pratiques

Un node Webhook n8n accepte n'importe quel JSON valide, quelle que soit sa structure. Envoyez {"email": "test"} à un workflow qui attend {"email": "...", "montant": 42}, et rien ne s'arrête au démarrage : le workflow avance, jusqu'à ce qu'un node plus loin — un appel LLM, une écriture Supabase, un envoi d'email — échoue sur une valeur absente ou du mauvais type. À ce stade, vous avez déjà payé l'appel au modèle et perdu la trace de ce qui a réellement été envoyé. Valider la forme des données dès leur entrée, avant tout traitement, coûte quelques lignes et évite ce genre de panne différée.

Pourquoi un payload « presque bon » casse un workflow plus loin

Un JSON malformé ne provoque presque jamais une erreur immédiate en entrée d'un workflow n8n. Le node Webhook reçoit la requête, la transforme en item, et la transmet telle quelle à la suite — champ manquant, type inattendu ou valeur null compris. L'erreur n'apparaît qu'au node qui tente réellement d'utiliser cette donnée : un $json.montant.toFixed(2) qui plante parce que montant est une chaîne, un prompt LLM qui reçoit undefined et hallucine une réponse cohérente sur une donnée absente, une ligne Supabase insérée avec un champ obligatoire vide qui casse une contrainte plus loin dans le pipeline.

Ce décalage entre l'entrée fautive et l'erreur visible n'est pas propre à n8n : c'est un classique de la sécurité applicative. Une étude de référence de Scholte, Balzarotti et Kirda, publiée dans la revue Computers & Security en 2012, a analysé plusieurs milliers de vulnérabilités web réelles et montré que la grande majorité ne provient pas d'un échec de sanitisation complexe, mais de l'absence pure et simple de validation en amont (Scholte, Balzarotti & Kirda, 2012). Le constat se transpose directement à un workflow d'automatisation : la faille n'est presque jamais dans la logique métier elle-même, mais dans l'hypothèse implicite que les données qui y entrent sont déjà correctes.

Authentifier n'est pas valider

Il est tentant de croire qu'un webhook protégé par Header Auth ou une signature HMAC est un webhook sûr. L'authentification répond à une seule question : qui a le droit d'appeler ce endpoint. Elle ne dit rien sur la forme de ce qui est envoyé. Un partenaire parfaitement légitime, avec la bonne clé API, peut très bien poster un JSON incomplet à cause d'un bug de son côté, d'un champ renommé sans prévenir, ou d'un formulaire front-end qui laisse passer un champ vide. La validation structurelle est une couche indépendante, complémentaire à l'authentification et à la déduplication par idempotence : chacune répond à une question différente sur la requête entrante.

L'approche native : valider sans aucune dépendance

Pour la majorité des workflows, un schema simple (quelques champs obligatoires, quelques types à vérifier) se traite très bien avec les nodes natifs de n8n, sans toucher à la configuration du serveur — donc aussi bien sur n8n Cloud qu'en self-hosted.

Placez un node IF ou Filter juste après le Webhook, avec une expression qui vérifie chaque contrainte :

{{
  $json.body.email &&
  $json.body.email.includes('@') &&
  typeof $json.body.montant === 'number' &&
  $json.body.montant > 0
}}

La branche « false » part vers un node Respond to Webhook qui renvoie un code 400 explicite plutôt que de laisser le workflow continuer sur des données invalides :

{
  "error": "payload_invalide",
  "details": "Le champ email est requis et montant doit être un nombre positif"
}

Cette approche a une limite claire : elle devient vite illisible dès qu'un schema dépasse trois ou quatre champs, ou qu'il faut valider une structure imbriquée (un tableau d'objets, des champs conditionnels). C'est là qu'un schema explicite prend le relais.

Aller plus loin : un vrai JSON Schema avec Ajv

Ajv est la librairie de référence pour valider du JSON contre un schema (spécification JSON Schema) en JavaScript. Elle tourne dans un node Code, à condition que votre instance soit self-hosted : comme tout module npm externe, elle doit être physiquement installée et autorisée via NODE_FUNCTION_ALLOW_EXTERNAL — la procédure complète est détaillée dans notre guide installer des modules npm dans le node Code.

const Ajv = require('ajv');
const ajv = new Ajv({ allErrors: true });

const schema = {
  type: 'object',
  required: ['email', 'montant'],
  properties: {
    email: { type: 'string', format: 'email' },
    montant: { type: 'number', minimum: 0 },
    devise: { type: 'string', enum: ['EUR', 'USD'] },
  },
  additionalProperties: false,
};

const validate = ajv.compile(schema);
const valid = validate($json.body);

if (!valid) {
  throw new Error(JSON.stringify(validate.errors));
}

return $input.all();

Ajv accepte des contraintes que les expressions natives ne couvrent pas confortablement : formats (email, date-time, uri), énumérations, bornes numériques, tableaux typés, oneOf/anyOf pour des champs conditionnels, et additionalProperties: false pour rejeter tout champ imprévu plutôt que de l'ignorer silencieusement. Le schema devient aussi une documentation exécutable du contrat attendu par le workflow — utile pour la personne qui le reprendra dans six mois.

Sur n8n Cloud : rester sur l'approche native

n8n Cloud permet d'installer des community nodes vérifiés depuis le panneau des nodes (plans Starter et supérieurs), et il en existe pour la validation JSON Schema. Mais un community node reste du code tiers exécuté sur votre instance : réservez cette option à des nodes effectivement marqués « vérifiés » par n8n, et pour un schema qui reste raisonnablement simple, les nodes IF/Filter natifs évitent d'ajouter une dépendance externe pour un gain marginal.

Où placer la validation dans le workflow

Le node de validation doit être le tout premier après le trigger — avant tout appel API, tout appel LLM, toute écriture en base. C'est le même principe que la limitation de débit sur un webhook qui appelle un LLM : bloquer tôt coûte une comparaison de chaînes, bloquer tard coûte un appel OpenAI ou Anthropic facturé pour rien. Branchez la sortie « invalide » vers un error workflow dédié plutôt que de laisser l'exception remonter brute : un 400 avec le détail des champs en tort permet à l'appelant de corriger son intégration, alors qu'un 500 générique ne dit rien d'exploitable.

Cas concret : un webhook de capture de leads

Un formulaire de contact qui poste vers n8n envoie typiquement { "nom": "...", "email": "...", "message": "...", "consentement": true }. Sans validation, un consentement manquant peut se retrouver enregistré comme undefined dans Supabase — un problème RGPD, pas seulement technique, puisque la preuve du consentement doit être traçable (voir notre guide sur la piste d'audit RGPD). Un schema Ajv avec consentement: { type: 'boolean', const: true } en champ requis rejette la requête avant tout enregistrement si la case n'a pas été cochée, plutôt que de découvrir le trou des mois plus tard lors d'un contrôle.

Le même principe s'applique à l'API POST /ask du Pack Assistant RAG (119 €) : valider que question est bien une chaîne non vide avant d'interroger la base vectorielle et le LLM évite de facturer un appel modèle pour un payload vide envoyé par erreur — un complément direct à l'authentification décrite dans notre guide sécuriser un webhook n8n.

Les erreurs qui coûtent cher

• Faire confiance au type qu'on croit recevoir : un champ numérique envoyé en chaîne par un formulaire front-end passe inaperçu jusqu'à un calcul qui échoue trois nodes plus loin.
• Valider après l'appel LLM plutôt qu'avant : l'ordre des nodes compte autant que la validation elle-même.
• additionalProperties absent d'un schema Ajv : un champ imprévu (parfois une tentative d'injection) traverse le workflow sans être ni rejeté ni signalé.
• Un message d'erreur générique : renvoyer un 400 sans préciser quel champ pose problème transforme chaque intégration ratée en séance de débogage à l'aveugle pour l'appelant.
• Confondre authentification et validation : les deux sont nécessaires, aucune ne remplace l'autre.

En résumé

Un payload JSON mal formé ne s'arrête jamais tout seul à l'entrée d'un workflow n8n — il continue jusqu'à casser quelque chose de moins prévisible, souvent après avoir déjà consommé une ressource payante. Pour un schema simple, les nodes IF ou Filter suffisent, sans dépendance ni configuration serveur. Pour un contrat de données plus riche — champs conditionnels, formats stricts, structures imbriquées —, Ajv dans un node Code sur une instance self-hosted couvre le reste, avec un schema qui documente autant qu'il valide. Dans les deux cas, la règle ne change pas : valider tôt, avant que l'erreur ne coûte plus cher qu'une comparaison.