n8n workflows

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

Exemple : article de presse sur le site de l’école

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

Le workflow n8n peut ensuite par exemple:

1. Transformer le court texte en un texte de brouillon soigné avec un nœud LLM et une prompt adaptée 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. Mettre hors ligne 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 saisit les informations nécessaires. n8n exécute ensuite les étapes automatisées et veille à ce que l’article de presse soit correctement publié sur le site.

Que fait cette intégration ?

Vous démarrez un workflow n8n depuis la vue d’ensemble du workflow. Seul le webhook de production, POST et l’authentification Header sont obligatoires. Les champs et les retours depuis n8n sont facultatifs et peuvent être configurés indépendamment.

• Si le workflow n’a pas de champs, le webhook est appelé immédiatement.
• S’il y a des champs, un formulaire s’ouvre d’abord. L’utilisateur remplit les champs et démarre ensuite le workflow avec le bouton.
• Les valeurs saisies sont envoyées en 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 est activé lors de l’enregistrement, le workflow peut renvoyer des étapes intermédiaires ou la fin vers AI-School.
• Si l’approbation est activée lors de l’enregistrement, l’utilisateur peut faire un choix directement dans AI-School. n8n reprend ensuite à partir de l’étape en attente.

Création du workflow n8n dans AI-School

Un administrateur enregistre le workflow comme suit:

1. Allez à Aide.
2. Ouvrez Workflows.
3. Choisissez Nouveau workflow n8n.
4. Saisissez 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. Cochez sous Retour d’informations depuis n8n uniquement les éléments qui sont réellement construits dans ce workflow n8n: progression, approbation et/ou fin du workflow.
7. Ajoutez éventuellement les champs qui doivent être transmis dans la requête POST.
8. Enregistrez le workflow.

Les trois options de retour d’informations sont désactivées par défaut. Si vous ajoutez plus tard des callbacks ou une étape d’approbation dans n8n, mettez à jour l’enregistrement dans AI-School. La boîte de dialogue saura alors s’il faut afficher uniquement une confirmation de démarrage ou attendre d’autres signaux.

Champs

• Les champs sont facultatifs.
• Chaque champ possède un nom de champ et un type.
• Les types de champ pris en charge sont texte court, texte long, nombre, oui/non, date, une seule sélection et plusieurs sélections.
• Pour Une sélection et Plusieurs sélections, ajoutez les options disponibles. Une Une sélection s’affiche sous forme de liste déroulante compacte; Plusieurs sélections affiche des cases à cocher. La ou les valeurs choisies sont envoyées dans le JSON body.
• Les champs obligatoires doivent être remplis avant de pouvoir démarrer le workflow.
• Le nom du champ devient la clé dans le JSON body envoyé à n8n.

Création d’un workflow compatible dans n8n

1. Dans n8n, créez un nouveau workflow.
2. Ajoutez en premier lieu un nœud Webhook.
3. Donnez à ce nœud exactement le nom Start workflow. Les exemples ci-après utilisent ce nom.
4. Définissez HTTP Method sur POST.
5. Choisissez Authentication sur Header Auth et sélectionnez une credential d’Header Auth.
6. Dans cette credential, saisissez le même nom d’en-tête et la même valeur secrète que pour le workflow dans AI-School.
7. Définissez Respond ou Response Mode sur Immediately. L’application reçoit alors immédiatement une confirmation de démarrage, tandis que n8n continue à travailler.
8. Copiez l’URL de production de la Webhook-node dans le champ n8n production URL dans AI-School. N’utilisez pas l’URL de test avec /webhook-test/.
9. Activez le workflow dans n8n.

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

Exemple du corps JSON

Si vous définissez des champs nommés prompt, klantnaam, doelgroepen et datum, n8n recevra par exemple ce corps JSON. AI-School ajoute automatiquement l’objet integration.

{
  "prompt": "Maak een korte samenvatting van de aanvraag.",
  "klantnaam": "Voorbeeldorganisatie",
  "doelgroepen": ["medewerkers", "ouders"],
  "datum": "2026-09-22",
  "integration": {
    "runId": "chat-document-id",
    "tenant": "default",
    "callbackUrl": "https://europe-west1-ai-school-pro.cloudfunctions.net/n8nWorkflowCallback",
    "callbackToken": "tijdelijk-token-voor-deze-uitvoering"
  }
}

Le token de rappel (callback) est lié à une seule exécution. Ne pas le stocker dans les logs, la configuration fixe ou d’autres systèmes.

Optionnel : renvoyer progression et achèvement

AI-School peut montrer seulement ce que renvoie n8n. Utilisez ces callbacks uniquement si vous avez activé lors de l’enregistrement la progression intermédiaire et/ou l’achèvement du workflow.

Configurer le nœud HTTP Request

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

2. Définissez Method sur POST.

3. Cliquez sur URL sur Expression.

4. Collez exactement cette expression:

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

5. Choisissez Authentication sur None. Le jeton temporaire sera 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": "Document maken"
  },
  "message": "Het document wordt gemaakt."
}

10. Choisissez Execute step tout en testant le workflow via l’application. Le nœud devrait renvoyer le statut 200.

Copiez ce nœud HTTP Request pour chaque statut de notification. Modifiez au moins eventId, step.id, step.label et message pour chaque copie.

Configurer le dernier callback

Si Het einde van de workflow melden est activé, il doit y avoir un dernier callback à la fin de chaque chemin possible. Utilisez type: "completed" en cas de succès, type: "failed" pour une erreur gérée et type: "rejected" lorsque l’utilisateur rejette le workflow.

Pour une exécution réussie, l’exemple suivant peut être utilisé comme corps:

{
  "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"
  }
}

Utilisez pour chaque callback une eventId différente dans le même exécution. Donnez aussi toujours une étiquette step.label claire: ce texte est visible dans la fenêtre d’exécution.

Optionnel : demander une approbation dans l’application

Configurer le nœud Wait

1. Ajoutez un nœud Wait à l’endroit où l’approbation est nécessaire.
2. Choisissez Resume sur On Webhook Call.
3. Définissez HTTP Method sur POST.
4. Choisissez Authentication sur Header Auth.
5. Sélectionnez exactement la 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é plus tôt et nommez-le Demander l’approbation.
7. Utilisez dans ce nœud la même URL et les mêmes en-têtes dynamiques. Remplacez uniquement le corps 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": "Document vérifier"
  },
  "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": "Rejeter" }
    ]
  }
}

Connectez Demander l’approbation au nœud Wait. L’utilisateur verra ensuite les boutons dans AI-School. L’URL de reprise secrète ne sera pas exposée au navigateur; le serveur envoie la sélection de manière sécurisée au nœud Wait.

Traiter le choix après le Wait

1. Ajoutez après le Wait un nœud Switch.
2. Utilisez comme valeur à vérifier:

{{ $json.body.decision }}

3. Créez par exemple une route pour approve et une route pour reject.
4. Faites terminer chaque route par un callback adapté: completed, rejected ou failed.

Une valeur de choix ne doit contenir que des lettres, chiffres, _ et -. Le label peut contenir du texte lisible.

Configurer le callback de production

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

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

N’insérez pas cette URL telle quelle dans chaque nœud de callback. Choisissez dans le champ URL du nœud HTTP Request une option Expression et utilisez:

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

AI-School fournit ainsi, à chaque démarrage, la bonne URL de production. L’URL fixe ci-dessus est uniquement à des fins de test pour vérifier l’expression pointant vers AI-School.

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

Renvoyer des erreurs inattendues

Une callback ordinaire failed ne fonctionne que si le nœud HTTP Request atteint le workflow. Utilisez également un Workflow d’erreur central n8n pour les erreurs inattendues des nœuds.

Créer un Workflow d’Erreur Central

1. Créez dans n8n un workflow séparé nommé AI-School - renvoi d’erreurs.
2. Ajoutez un nœud Error Trigger.
3. Ajoutez ensuite un nœud HTTP Request.
4. Définissez Method sur POST.
5. Saisissez 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 secrète standard que vous reçoit du gestionnaire de plateforme
   Content-Type	application/json

8. Activez Send Body, choisissez JSON et copiez ce corps:

{
  "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 dans Error Workflow ce nouveau Workflow d’erreur.

Envoyez immédiatement après le Start workflow au moins une progression avec executionId: "{{ $execution.id }}". Cela permet à l’application de savoir à quelle exécution une erreur inattendue d’n8n est liée.

Restrictions importantes

• Seuls les déclencheurs webhook sont pris en charge.
• Seuls les URLs de webhook de production sont prises en charge.
• Les URLs de test webhook avec /webhook-test/ sont refusées.
• Seule la méthode POST est prise en charge.
• Seule l’authentification d’en-tête générique est prise en charge.
• La valeur d’en-tête est traitée comme secrète par l’application.
• Les tokens de callback et les URLs de reprise ne sont traités que côté serveur et ne sont pas directement accessibles 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 les mêmes 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.
• Pas de requête dans n8n: vérifiez que le workflow commence par un déclencheur webhook et utilise POST.
• La fenêtre d’exécution tourne sans fin: si vous avez activé Het einde van de workflow melden, vérifiez si n8n envoie un callback final completed, failed ou rejected. Si vous n’attendez aucun retour, désactivez ces trois options dans l’enregistrement.
• Pas de progression visible: vérifiez si Tussentijdse voortgang melden est activé lors de l’enregistrement, ou si l’objet integration est conservé et si chaque callback a un eventId unique.
• Boutons d’approbation qui ne fonctionnent pas: vérifiez le nœud Wait, le resumeUrl, l’authentification d’en-tête et les caractères autorisés dans choices[].value.