n8n ワークフロー

AI-School は production webhook を介して n8n ワークフローを起動できます。これは、AI-School の外部で自動化プロセスを開始したい場合、例えばタスクの作成、CRM レコードの更新、レポートフローの開始、フォームデータを別システムへ転送などを行うときに便利です。

例: 学校ウェブサイトの記事を公開

学校が WordPress ウェブサイトに記事を公開する n8n ワークフローを作成しているとします。AI-School では短いテキストを入力するだけで、プロジェクト週、スポーツデー、オープンデーなどについての数文といった例を入れます。そのテキストを使って n8n のワークフローを開始します。

n8n のワークフローは次のような処理を行えます。

1. 短いテキストから、学校のトーンにあったプロンプトとLLMノードを使ってきれいな概説文を作成する。
2. 学校のカラーと認識しやすいスタイルで適切なイラストを作成するため、2つ目の LLN ノードを使う。
3. テキストと画像をブログ投稿として公開する、または WordPress ウェブサイトに公開する。

このように、AI-School と n8n は協働します。AI-School ではユーザーがワークフローを選択し、必要情報を入力します。n8n が自動化されたステップを実行し、ニュース記事がウェブサイトに正しく表示されるようにします。

この統合の機能

ワークフローの概要画面から n8n のワークフローを起動します。production webhook、POST、Header Authentication のみが必須です。n8n からのフィールドと返戻通知は任意で、個別に設定可能です。

• ワークフローにフィールドがない場合、Webhook は直ちに呼び出されます。
• ワークフローにフィールドがある場合、最初にフォームが開きます。ユーザーがフィールドを入力し、ボタンでワークフローを開始します。
• 入力値はJSONとして POST リクエストで n8n の webhook に送信されます。
• 返戻通知がない場合、AI-School はワークフローが開始されたことだけを通知し、n8n 側の処理を継続します。ウィンドウにはスピナーは表示されず、すぐに閉じられます。
• 登録時にこの機能を有効にしている場合、ワークフローは途中のステップや終了を AI-School に返すことがあります。
• 登録時に承認を有効にしている場合、ユーザーは AI-School 内で直接選択できます。その後、n8n は待機中のステップから処理を続行します。

AI-School での n8n ワークフロー作成

管理者は以下の手順でワークフローを登録します。

1. Assistenten へ移動。
2. Workflows を開く。
3. Nieuwe n8n workflow を選択。
4. ワークフローの名前と n8n の production URL を入力。
5. Header authentication を header name と秘密値で設定。
6. Terugmeldingen uit n8n の下で、実際にこの n8n ワークフローで構築されている部分（進行状況、承認、またはワークフローの終了）のみをチェックします。
7. POST リクエストで送信するフィールドを追加します。
8. ワークフローを保存。

3つの返戻通知オプションはデフォルトで OFF です。後で n8n にコールバックや承認ステップを設定する場合、AI-School 側の登録も更新してください。ダイアログは開始通知のみを表示するか、さらなる信号を待機するかを認識します。

フィールド

• フィールドは任意です。
• 各フィールドには1つのフィールド名とタイプがあります。
• サポートされるフィールドタイプは、短いテキスト、長いテキスト、数値、はい/いいえ、日付、1つの選択、複数選択です。
• 「1つの選択」と「複数選択」では、利用可能なオプションを追加します。「1つの選択」はコンパクトな選択リストとして表示されます。「複数選択」はチェックボックスを表示します。選択された値は JSON ボディに送信されます。
• 必須フィールドは、ワークフローを開始する前に入力済みである必要があります。
• フィールド名は、n8n に送られる JSON ボディのキーになります。

n8n での互換性のあるワークフロー作成

1. n8n で新しいワークフローを作成。
2. 最初のノードとして Webhook を追加。
3. このノードに正確に名前を付けて Start workflow。以降のサンプルはこの名前を使用します。
4. HTTP Method を POST に設定。
5. Authentication は Header Auth を選択。
6. 先ほどの AI-School のワークフローと同じヘッダ名と秘密値を credential に入力。
7. Respond または Response Mode を Immediately に設定。これにより、アプリはすぐに開始成功を受け取り、n8n は処理を続行します。
8. Webhook ノードの Production URL を AI-School の n8n production URL の欄へコピー。テスト用の URL は使わないでください、/webhook-test/ にはしません。
9. n8n でワークフローを有効化。

AI-School のデータは n8n の body の下にあります。統合データは body.integration の下にあります。Edit Fields、Set、Code ノードでこれらのデータを削除しないでください。以下の例では、常にノード Start workflow から直接値を取得しています。

JSON ボディの例

prompt、klantnaam、doelgroepen、datum という名前でフィールドを定義すると、n8n はこの JSON ボディを受け取ります。AI-School は自動的に 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"
  }
}

callbacktoken は 1 回の実行に対するものです。ログや設定、他のシステムには保存しないでください。

オプション: 進行状況と完了を返す

AI-School は n8n が返す情報のみを表示します。登録時に「途中経過の報告」と「ワークフローの完了報告」を有効にしている場合に限り、このコールバックを使用します。

HTTP Request ノードの設定

1. Meld voortgang などの名前で HTTP Request ノードを追加します。

2. Method を POST に設定。

3. URL は Expression を選択。

4. 正確な式を貼り付けます：

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

5. Authentication は None を選択。暫定トークンは次のステップでヘッダーとして追加されます。

6. Send Headers を ON にして、以下のヘッダを追加します：

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

7. Send Body を ON にします。

8. Body Content Type: JSON と Specify Body: Using JSON を選択。

9. 以下の JSON を 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. アプリを使ってワークフローをテストしながら Execute step を選択します。ノードはステータス 200 を返すはずです。

この HTTP Request ノードは、各ステータスメッセージごとに複製してください。コピーごとに少なくとも eventId、step.id、step.label、message を変更します。

最後のコールバック設定

「Het einde van de workflow melden」 が有効になっている場合、各ルートの最後に最後のコールバックを置く必要があります。成功時は type: "completed"、自分で処理するエラーは type: "failed"、ユーザーがワークフローを拒否した場合は type: "rejected" を使用します。

成功した実行の例:

{
  "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 afgerond"
  },
  "message": "De workflow is afgerond.",
  "output": {
    "resultaat": "Korte omschrijving of link naar het resultaat"
  }
}

各コールバックごとにユニークな eventId を使用します。ユーザーには常に明確な step.label が表示されるようにしてください。

アプリ内の承認を任意で設定

Wait ノードの設定

1. 承認が必要な場所に Wait ノードを追加します。
2. Resume を On Webhook Call に設定。
3. HTTP Method を POST に設定。
4. Authentication は Header Auth を選択。
5. Start workflow ノードと同じ Header Auth のクレデンシャルを選択。
6. Wait ノードの前に、先ほど設定した HTTP Request ノードのコピーを配置し、名前を Vraag goedkeuring とします。
7. このノードでは、同じ動的 URL と headers を使用します。JSON ボディだけを以下の内容に置き換えます：

{
  "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 controleren"
  },
  "approval": {
    "question": "Mag de workflow doorgaan?",
    "context": "Controleer eerst het gegenereerde document.",
    "resumeUrl": "{{ $execution.resumeUrl }}",
    "choices": [
      { "value": "approve", "label": "Goedkeuren" },
      { "value": "reject", "label": "Afwijzen" }
    ]
  }
}

Vraag goedkeuring ノードを Wait ノードに接続します。ユーザーは AI-School でボタンを見ます。秘密の resume-url はブラウザには渡されず、サーバーが Wait ノードへ安全に選択を送信します。

Wait ノード後の選択処理

1. Wait ノードの後に Switch ノードを追加します。
2. チェックする値として以下を使用します：

{{ $json.body.decision }}

3. 例えば approve 用と reject 用のルートを作成します。
4. 各ルートは適切な completed、rejected、または failed コールバックで終了します。

選択値には英字、数字、アンダースコア、ハイフンのみを許可します。ラベルには通常の読めるテキストを使えます。

本番用のコールバック URL の設定

AI-School の本番用コールバック URL は次のとおりです。

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

この URL を各コールバックノードの固定テキストとして貼り付けないでください。HTTP Request ノードの URL フィールドで Expression を選択し、次を使用します。

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

これにより、AI-School は開始時に適切な production URL を自動的に提供します。上記の固定 URL は、テスト時に式が AI-School を参照しているかを確認するためだけに使用します。

callables triggerCustomN8nWorkflow、triggerN8nWorkflow、resumeN8nWorkflow はアプリ自体が呼び出します。これらの URL を n8n に設定する必要はありません。

不測のエラーを返す

通常の failed コールバックは、該当する HTTP Request ノードにワークフローが到達した場合にのみ機能します。予期せぬノードエラーについては、中央の n8n エラーワークフローを用意してください。

中央エラーワークフローの作成

1. n8n で名前を「AI-School - fouten terugsturen」とする別のワークフローを作成します。
2. Error Trigger ノードを追加。
3. 次に HTTP Request ノードを追加。
4. Method を POST に設定。
5. 固定の本番 URL を以下に設定：

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

6. Authentication: None を選択。

7. Send Headers を ON にして、次を追加：

   Name	Value
   n8n-handihow-name	プラットフォーム管理者から受け取った秘密のデフォルト値
   Content-Type	application/json

8. Send Body を ON にして JSON を選択し、以下のボディを貼り付けます：

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

9. エラーワークフローを有効化します。
10. 通常ワークフローの設定を開き、Error Workflow にこの新しいエラーワークフローを選択します。

「Start workflow」実行直後には、少なくとも1つの進行コールバックを executionId: "{{ $execution.id }}" を付けて送信してください。これにより、不測の n8n エラーがどの実行に属するかがアプリに通知されます。

重要な制限事項

• ウェブフックトリガーのみサポート。
• 本番用 webhook URL のみサポート。
• /webhook-test/ を含むテスト用 webhook URL は拒否。
• POST のみサポート。
• ジェネリックなヘッダ認証のみサポート。
• ヘッダ値はアプリケーション側で機密として扱われます。
• コールバックトークンと resume-url はサーバーサイドでのみ処理され、ユーザーには直接利用できません。
• テナントはログイン済みユーザーのサーバーサイドで決定され、ブラウザが送信する値ではありません。

問題の解決

• 404 または webhook が登録されていない場合: n8n でワークフローを有効化し、本番 URL を使用。
• 認証エラー: ヘッダ名と値が両方のシステムで正確に一致しているか確認。
• データ欠如: アプリ内のフィールド名が n8n が期待するキーと一致しているか確認。
• n8n にリクエストがない: ワークフローが webhook トリガーから始まり POST を使っているか確認。
• 実行ウィンドウが回転し続ける: 「Het einde van de workflow melden」を ON にしている場合、n8n が最後の completed、failed、または rejected コールバックを送信するか確認。返戻通知が不要な場合は、登録時にすべてのオプションを OFF にしてください。
• 進行状況が見えない: 登録時に Tussentijdse voortgang melden を ON にするか、integration オブジェクトを保持し、各コールバックに一意の eventId があるか確認。
• 承認ボタンが機能しない: Wait ノード、resumeUrl、ヘッダ認証、そして choices[].value の許容文字を確認。