Recevoir un fichier uploadé dans n8n : le Webhook face au multipart/form-data

Le scénario revient souvent : un formulaire HTML avec un champ <input type="file"> poste vers un Webhook n8n, et l'exécution s'affiche bien dans l'éditeur — mais l'onglet Binary du node reste désespérément vide, ou le fichier apparaît sous une clé inattendue comme file0. Rien n'est cassé côté serveur : c'est la mécanique du multipart/form-data, différente de celle d'un simple JSON, qui n'est pas configurée comme n8n l'attend. Ce guide détaille comment le node Webhook reçoit réellement un fichier, le rôle exact du champ Binary Property, et les pièges qui expliquent 90 % des « fichier vide » côté n8n.

JSON contre multipart/form-data : deux mécaniques différentes

Un Webhook n8n classique reçoit un corps JSON (Content-Type: application/json), lu directement en $json. Un upload de fichier depuis un <form> HTML ou un FormData() JavaScript emprunte un chemin différent : la requête est encodée en multipart/form-data, un format qui découpe le corps en plusieurs blocs séparés par un boundary — un champ texte par bloc, un fichier binaire par bloc, chacun avec son propre en-tête Content-Disposition: form-data; name="...".

n8n distingue automatiquement les deux : les champs texte du formulaire arrivent dans $json.body, et chaque fichier atterrit dans $binary, sous une clé qui reprend par défaut le name de l'<input> HTML correspondant. Un formulaire avec <input type="file" name="justificatif"> produira donc un $binary.justificatif accessible dans les nodes suivants — à condition que la requête soit effectivement envoyée en multipart, pas en JSON avec le fichier encodé à la main en base64 (une erreur fréquente quand le formulaire est construit avec fetch() sans passer par un objet FormData).

Le champ Binary Property : utile pour un fichier, piégeux pour plusieurs

Dans les options du node Webhook, le champ Binary Property permet de forcer le nom de la clé sous laquelle le fichier reçu sera exposé dans $binary, plutôt que de dépendre du nom de champ HTML. C'est pratique pour un formulaire simple, à un seul champ fichier dont le nom peut varier.

Le piège apparaît avec plusieurs champs fichier dans le même formulaire (par exemple piece_identite et justificatif_domicile pour un dossier d'onboarding). Si vous renseignez Binary Property, n8n regroupe tous les fichiers reçus et les renomme génériquement en file0, file1, etc. — vous perdez l'association entre chaque fichier et son champ d'origine, un comportement documenté à plusieurs reprises sur le forum communautaire n8n. La bonne pratique dans ce cas : laissez Binary Property vide. Chaque fichier reste alors accessible sous le nom exact de son champ HTML ($binary.piece_identite, $binary.justificatif_domicile), sans manipulation supplémentaire.

Tester avant de brancher un vrai formulaire

Avant de connecter un formulaire de production, validez la réception avec curl, qui construit un multipart/form-data correct sans effort :

curl -X POST https://votre-instance.n8n.cloud/webhook/upload-test \
  -F "justificatif=@facture.pdf" \
  -F "commentaire=Test upload"

Le node Webhook doit alors afficher commentaire dans $json.body et justificatif dans l'onglet Binary, avec sa taille, son type MIME (fileType) et son nom d'origine (fileName) déjà renseignés par n8n. Notre guide sur les webhooks n8n en local détaille comment reproduire ce test sans exposer d'URL publique, via l'URL de test de l'éditeur.

Pièges courants et messages d'erreur

• Fichier vide malgré une requête qui semble correcte : vérifiez dans l'onglet Réseau du navigateur que le Content-Type envoyé est bien multipart/form-data; boundary=... et non application/json. Un FormData() JavaScript construit ce Content-Type automatiquement — ne le fixez jamais manuellement dans les en-têtes de votre appel, sinon le boundary disparaît et n8n ne peut plus découper le corps.
• Erreur 413 ou fichier tronqué : le fichier dépasse N8N_FORMDATA_FILE_SIZE_MAX (200 Mio par défaut en self-hosted) ou la limite spécifique de votre offre n8n Cloud. Notre guide sur les fichiers volumineux et le binary data détaille cette variable et le comportement mémoire associé ; notre article dédié à l'erreur 413 couvre le cas des payloads JSON classiques.
• Vérification de signature qui échoue après un upload : si votre webhook doit aussi vérifier une signature HMAC (cas d'un webhook Stripe ou GitHub, par exemple), le corps brut nécessaire au calcul de la signature n'est généralement pas disponible de la même façon en multipart qu'en JSON. Ce cas de figure sort du périmètre d'un simple formulaire ; notre guide sur la sécurisation des webhooks n8n détaille les options pour ce scénario plus avancé.

Que faire du fichier une fois reçu

Une fois le binaire disponible sous sa clé $binary, il circule comme n'importe quel fichier n8n : un node HTTP Request peut le relayer vers Google Drive, S3 ou un CRM, un node dédié peut l'archiver, ou — cas fréquent pour un dossier client — il peut alimenter directement un pipeline d'ingestion documentaire. C'est exactement le rôle du workflow Ingestion PDF vers Supabase pgvector du Pack Assistant RAG (119 €) : un client dépose un PDF via un formulaire web, et le document est découpé, vectorisé et rendu interrogeable sans étape manuelle. Le même principe s'applique aux pièces jointes d'un dossier d'audit, pris en charge par le workflow d'enregistrement du Pack Conformité & Audit (149 €).

Avant de traiter le fichier, validez-le plutôt que de lui faire confiance : type MIME réel ($binary.justificatif.fileType), extension attendue, taille raisonnable. Une étude récente de Chen, Li, Pan, Lu, Chen et Ji, « URadar: Discovering Unrestricted File Upload Vulnerabilities via Adaptive Dynamic Testing » (IEEE Transactions on Information Forensics and Security, 2023 — voir l’étude), a mis au jour des dizaines de vulnérabilités d'exécution de code exploitables via des points d'upload insuffisamment contrôlés, dans des applications web réelles. La leçon transpose directement à un workflow n8n exposé publiquement : ne jamais exécuter, interpréter ou servir tel quel un fichier reçu par webhook sans avoir vérifié son type réel, et limiter les extensions acceptées à ce que le workflow sait effectivement traiter.

Webhook ou Form Trigger : lequel choisir

Si le formulaire n'a pas besoin d'exister ailleurs que dans n8n, le node Form Trigger simplifie nettement la prise en charge d'un upload : rendu du formulaire, validation de champ et gestion binaire sont natifs, sans configuration multipart manuelle. Le Webhook reste le bon choix dès que le fichier provient d'un formulaire ou d'une application déjà existante, que vous ne contrôlez pas depuis l'éditeur n8n — un site vitrine, une application interne, ou l'intégration décrite dans notre guide complet sur le node Webhook.

Ce qu'il faut retenir

Un upload de fichier vers un Webhook n8n suit une mécanique bien distincte d'un webhook JSON classique : le multipart/form-data sépare champs texte et fichiers, et chaque fichier atterrit dans $binary sous le nom de son champ HTML — sauf si vous forcez une clé unique via Binary Property, ce qui casse l'association dès qu'il y a plusieurs fichiers. Testez toujours avec curl -F avant de brancher un vrai formulaire, surveillez les limites de taille, et validez le fichier reçu (type réel, extension, taille) avant de le transmettre à la suite du workflow.