workflows n8n

AI-School peut lancer des workflows n8n via un webhook de production. C’est utile lorsque vous souhaitez démarrer en dehors d’AI-School un processus automatisé, par exemple créer une tâche, mettre à jour un enregistrement CRM, lancer un flux de rapport ou transmettre des données de formulaire vers un autre système.

Exemple : article d’actualité sur le site de l’école

Supposons que l’école ait créé un workflow n8n qui publie un article d’actualité sur le site WordPress de l’école. Dans AI-School, vous ne saisissez alors qu’un court texte, par exemple quelques phrases sur une semaine de projet, une journée sportive ou une journée portes ouvertes. Avec ce texte, vous lancez le workflow dans n8n.

Le workflow n8n peut ensuite par exemple :

1. Transformer ce court texte en un brouillon soigné à l’aide d’un nœud LLM et d’un prompt adapté au ton de l’école.
2. Faire créer une illustration adaptée avec un deuxième nœud LLM, par exemple dans les couleurs de l’école et dans un style illustratif reconnaissable.
3. Préparer ou publier le texte et l’image en tant qu’article de blog sur le site WordPress.

Ainsi, AI-School et n8n travaillent ensemble : dans AI-School, l’utilisateur choisit le workflow et remplit les informations nécessaires. n8n exécute ensuite les étapes automatisées et veille à ce que l’article d’actualité arrive proprement sur le site.

Que fait cette intégration ?

Vous démarrez un workflow n8n depuis l’aperçu des workflows. Seuls le webhook de production, POST et Header Auth sont obligatoires. Les champs et les retours de n8n sont facultatifs et peuvent être configurés indépendamment les uns des autres.

• Si le workflow n’a aucun champ, le webhook est appelé immédiatement.
• Si le workflow a des champs, un formulaire s’ouvre d’abord. L’utilisateur remplit les champs puis démarre le workflow avec le bouton.
• Les valeurs saisies sont envoyées sous forme de JSON dans une requête POST vers le webhook n8n.
• Sans retours, AI-School confirme seulement que le workflow a démarré et continue dans n8n. La fenêtre n’affiche pas de spinner et peut être fermée immédiatement.
• Si cela a été activé lors de l’enregistrement, le workflow peut renvoyer des étapes intermédiaires ou la fin vers AI-School.
• Si l’approbation a été activée lors de l’enregistrement, l’utilisateur peut faire un choix directement dans AI-School. n8n continue ensuite à partir de l’étape d’attente.

Créer un workflow n8n dans AI-School

Un administrateur enregistre le workflow comme suit :

1. Allez dans Assistants.
2. Ouvrez l’onglet Assistants de workflow.
3. Dans la carte en haut, cliquez sur Nouveau workflow et choisissez workflow n8n.
4. Renseignez le nom du workflow et l’URL de production n8n.
5. Configurez Header authentication avec un nom d’en-tête et une valeur d’en-tête secrète.
6. Sous Retours de n8n, cochez uniquement les éléments réellement construits dans ce workflow n8n : progression, approbation et/ou fin du workflow.
7. Ajoutez éventuellement les champs qui doivent être envoyés dans la requête POST.
8. Enregistrez le workflow.

Les trois options de retour sont désactivées par défaut. Si vous ajoutez plus tard des callbacks ou une étape d’approbation dans n8n, mettez aussi à jour l’enregistrement dans AI-School. La boîte de dialogue sait ainsi si elle doit seulement afficher une confirmation de démarrage ou continuer à attendre d’autres signaux.

Champs

• Les champs sont facultatifs.
• Chaque champ a un nom de champ et un type.
• Les types de champ pris en charge sont : texte court, texte long, nombre, oui/non, date, un choix et plusieurs choix.
• Pour Un choix et Plusieurs choix, ajoutez les options disponibles. Un choix est affiché sous forme de liste déroulante compacte ; Plusieurs choix affiche des cases à cocher. La ou les valeurs choisies sont envoyées dans le body JSON.
• Les champs obligatoires doivent être remplis avant que le workflow puisse être démarré.
• Le nom du champ devient la clé dans le body JSON envoyé à n8n.

Créer un workflow compatible dans n8n

1. Créez un nouveau workflow dans n8n.
2. Ajoutez comme premier nœud un Webhook.
3. Donnez exactement à ce nœud le nom Start workflow. Les exemples ci-dessous utilisent ce nom.
4. Réglez HTTP Method sur POST.
5. Dans Authentication, choisissez Header Auth et sélectionnez un credential Header Auth.
6. Renseignez dans ce credential le même nom d’en-tête et la même valeur secrète que dans le workflow d’AI-School.
7. Réglez Respond ou Response Mode sur Immediately. L’application reçoit alors immédiatement une confirmation de démarrage réussie, tandis que n8n poursuit le traitement.
8. Copiez l’URL de production du nœud Webhook dans le champ n8n production-url d’AI-School. N’utilisez pas l’URL de test avec /webhook-test/.
9. Activez le workflow dans n8n.

Les données provenant d’AI-School se trouvent dans body dans n8n. Les données d’intégration se trouvent donc sous body.integration. Ne supprimez pas ces données dans un nœud Edit Fields, Set ou Code. Les exemples ci-dessous les relisent toujours directement depuis le nœud Start workflow.

Exemple du body JSON

Si vous définissez des champs nommés prompt, nom_client, groupes_cibles et date, n8n reçoit par exemple ce body JSON. AI-School ajoute automatiquement l’objet integration.

{
  "prompt": "Rédige un bref résumé de la demande.",
  "nom_client": "Organisation d’exemple",
  "groupes_cibles": ["personnel", "parents"],
  "date": "2026-09-22",
  "integration": {
    "runId": "chat-document-id",
    "tenant": "default",
    "callbackUrl": "https://europe-west1-ai-school-pro.cloudfunctions.net/n8nWorkflowCallback",
    "callbackToken": "jeton-temporaire-pour-cette-exécution"
  }
}

Le token de callback appartient à une seule exécution. Ne le stockez pas dans les logs, une configuration fixe ou d’autres systèmes.

Optionnel : renvoyer la progression et la fin

AI-School ne peut afficher que ce que n8n renvoie. N’utilisez ces callbacks que si vous avez activé lors de l’enregistrement Signaler la progression intermédiaire et/ou Signaler la fin du workflow.

Configurer un nœud HTTP Request

1. Ajoutez un nœud HTTP Request et nommez-le par exemple Signaler la progression.

2. Réglez Method sur POST.

3. Cliquez sur Expression pour URL.

4. Collez exactement cette expression :

   {{ $('Start workflow').first().json.body.integration.callbackUrl }}

5. Dans Authentication, choisissez None. Le jeton temporaire est ajouté comme en-tête à l’étape suivante.

6. Activez Send Headers et ajoutez ces deux en-têtes :

   Name	Value
   Authorization	Bearer {{ $('Start workflow').first().json.body.integration.callbackToken }}
   Content-Type	application/json

7. Activez Send Body.

8. Choisissez Body Content Type: JSON et Specify Body: Using JSON.

9. Collez le JSON ci-dessous dans le champ JSON :

{
  "tenant": "{{ $('Start workflow').first().json.body.integration.tenant }}",
  "runId": "{{ $('Start workflow').first().json.body.integration.runId }}",
  "eventId": "document-maken-gestart",
  "type": "progress",
  "executionId": "{{ $execution.id }}",
  "step": {
    "id": "document_maken",
    "label": "Création du document"
  },
  "message": "Le document est en cours de création."
}

10. Choisissez Execute step pendant que vous testez le workflow via l’application. Le nœud doit recevoir un statut 200.

Copiez ce nœud HTTP Request pour chaque message d’état. Modifiez au minimum eventId, step.id, step.label et message pour chaque copie.

Configurer le dernier callback

Si Signaler la fin du workflow est activé, un dernier callback doit être placé à la fin de chaque route possible. Utilisez type: "completed" en cas de succès, type: "failed" pour une erreur que vous gérez vous-même et type: "rejected" lorsque l’utilisateur refuse le workflow.

Pour une exécution réussie, le body peut ressembler à ceci :

{
  "tenant": "{{ $('Start workflow').first().json.body.integration.tenant }}",
  "runId": "{{ $('Start workflow').first().json.body.integration.runId }}",
  "eventId": "workflow-afgerond",
  "type": "completed",
  "executionId": "{{ $execution.id }}",
  "step": {
    "id": "afronding",
    "label": "Workflow terminé"
  },
  "message": "Le workflow est terminé.",
  "output": {
    "resultaat": "Brève description ou lien vers le résultat"
  }
}

Dans une même exécution, utilisez un eventId différent pour chaque callback. Utilisez toujours aussi un step.label clair : c’est ce texte que l’utilisateur voit dans la fenêtre d’exécution.

Optionnel : demander une approbation dans l’application

Configurer un nœud Wait

1. Ajoutez un nœud Wait à l’endroit où l’approbation est nécessaire.
2. Dans Resume, choisissez On Webhook Call.
3. Réglez HTTP Method sur POST.
4. Dans Authentication, choisissez Header Auth.
5. Sélectionnez le même credential Header Auth que pour le nœud Start workflow.
6. Avant le nœud Wait, placez une copie du nœud HTTP Request configuré précédemment et nommez-la Demander approbation.
7. Utilisez dans ce nœud la même URL dynamique et les mêmes en-têtes. Remplacez uniquement le body JSON par :

{
  "tenant": "{{ $('Start workflow').first().json.body.integration.tenant }}",
  "runId": "{{ $('Start workflow').first().json.body.integration.runId }}",
  "eventId": "controle-document",
  "type": "approval_required",
  "executionId": "{{ $execution.id }}",
  "step": {
    "id": "controle_document",
    "label": "Vérifier le document"
  },
  "approval": {
    "question": "Le workflow peut-il continuer ?",
    "context": "Vérifiez d’abord le document généré.",
    "resumeUrl": "{{ $execution.resumeUrl }}",
    "choices": [
      { "value": "approve", "label": "Approuver" },
      { "value": "reject", "label": "Refuser" }
    ]
  }
}

Reliez Demander approbation au nœud Wait. L’utilisateur voit ensuite les boutons dans AI-School. L’URL de reprise secrète n’est pas transmise au navigateur ; le serveur envoie le choix en toute sécurité au nœud Wait.

Traiter le choix après le nœud Wait

1. Ajoutez un nœud Switch après le nœud Wait.

2. Utilisez comme valeur à contrôler :

   {{ $json.body.decision }}

3. Créez par exemple une route pour approve et une route pour reject.

4. Terminez chaque route par un callback approprié completed, rejected ou failed.

Une valeur de choix ne peut contenir que des lettres, des chiffres, _ et -. Le label peut en revanche contenir un texte normal lisible.

Configurer l’URL de callback de production

L’URL de callback de production pour AI-School est :

https://europe-west1-ai-school-pro.cloudfunctions.net/n8nWorkflowCallback

Ne collez pas cette URL comme texte fixe dans chaque nœud callback. Choisissez Expression dans le champ URL du nœud HTTP Request et utilisez :

{{ $('Start workflow').first().json.body.integration.callbackUrl }}

AI-School fournit ainsi automatiquement la bonne URL de production à chaque démarrage. L’URL fixe ci-dessus ne sert qu’à vérifier pendant les tests que l’expression pointe bien vers AI-School.

Les callables triggerCustomN8nWorkflow, triggerN8nWorkflow et resumeN8nWorkflow sont appelées par l’application elle-même. Vous n’avez pas besoin de configurer ces URL dans n8n.

Renvoyer les erreurs inattendues

Un simple callback failed ne fonctionne que lorsque le workflow atteint le nœud HTTP Request concerné. Pour les erreurs inattendues de nœud, utilisez en plus un workflow d’erreur n8n central.

Créer un workflow d’erreur central

1. Créez dans n8n un workflow séparé nommé AI-School - erreurs à renvoyer.

2. Ajoutez un nœud Error Trigger.

3. Ajoutez ensuite un nœud HTTP Request.

4. Réglez Method sur POST.

5. Renseignez cette URL de production fixe dans URL :

   https://europe-west1-ai-school-pro.cloudfunctions.net/n8nWorkflowExecutionFailed

6. Choisissez Authentication: None.

7. Activez Send Headers et ajoutez :

   Name	Value
   n8n-handihow-name	la valeur standard secrète que vous recevez de l’administrateur de la plateforme
   Content-Type	application/json

8. Activez Send Body, choisissez JSON et collez ce body :

{
  "executionId": "{{ $json.execution.id }}",
  "workflowId": "{{ $json.workflow.id }}",
  "workflowName": "{{ $json.workflow.name }}",
  "lastNode": "{{ $json.execution.lastNodeExecuted }}",
  "message": "{{ $json.execution.error.message }}"
}

9. Activez le workflow d’erreur.
10. Ouvrez les paramètres du workflow normal et sélectionnez ce nouveau workflow d’erreur dans Error Workflow.

Après Start workflow, envoyez toujours au moins un callback de progression avec executionId: "{{ $execution.id }}". L’application sait ainsi à quelle exécution une erreur inattendue de n8n appartient.

Limitations importantes

• Seuls les déclencheurs webhook sont pris en charge.
• Seules les URL de webhook de production sont prises en charge.
• Les URL de webhook de test avec /webhook-test/ sont refusées.
• Seul POST est pris en charge.
• Seule l’authentification header générique est prise en charge.
• La valeur de l’en-tête est traitée comme secrète dans l’application.
• Les tokens de callback et les URL de reprise sont traités uniquement côté serveur et ne sont pas directement disponibles pour les utilisateurs.
• Le tenant est déterminé côté serveur à partir de l’utilisateur connecté, et non à partir d’une valeur envoyée par le navigateur.

Dépannage

• 404 ou webhook non enregistré : activez le workflow dans n8n et utilisez l’URL de production.
• Erreur d’authentification : vérifiez que le nom d’en-tête et la valeur sont exactement identiques dans les deux systèmes.
• Données manquantes : vérifiez que les noms de champs dans l’application correspondent aux clés attendues par n8n.
• Aucune requête dans n8n : vérifiez que le workflow commence par un déclencheur webhook et utilise POST.
• La fenêtre d’exécution reste ouverte : si vous avez activé Signaler la fin du workflow, vérifiez que n8n envoie bien un dernier callback completed, failed ou rejected. Si vous n’attendez aucun retour, désactivez les trois options lors de l’enregistrement.
• Aucune progression visible : vérifiez que Signaler la progression intermédiaire est activé lors de l’enregistrement, que l’objet integration est conservé et que chaque callback possède un eventId unique.
• Les boutons d’approbation ne fonctionnent pas : vérifiez le nœud Wait, resumeUrl, l’authentification header et les caractères autorisés dans choices[].value.