n8n ワークフロー

AI-School は本番用 webhook を通じて n8n ワークフローを開始できます。これは、AI-School の外部で自動化された処理を開始したいときに便利です。たとえば、タスクの作成、CRM レコードの更新、レポートフローの開始、またはフォームデータを別システムへ連携する場合などです。

例: 学校サイトへのニュース記事

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

その後、n8n ワークフローはたとえば次のように動作できます。

LLM ノードと、学校のトーンに合ったプロンプトを使って、短いテキストから整った下書き文を作成する。
2 つ目の LLM ノードで、学校の色合いと認識しやすいイラスト風のスタイルの適切な画像を生成する。
テキストと画像をブログ投稿として WordPress サイトに下書き保存または公開する。

このように、AI-School と n8n は連携して動作します。AI-School ではユーザーがワークフローを選び、必要な情報を入力します。n8n はその後、自動化されたステップを実行し、ニュース記事をサイトにきれいに掲載します。

この統合は何をするのか？

ワークフロー一覧から n8n ワークフローを開始します。必須なのは本番用 webhook、POST、Header Auth のみです。n8n からのフィールドと通知は任意であり、相互に独立して設定できます。

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

AI-School で n8n ワークフローを作成する

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

アシスタント に移動します。
ワークフローアシスタント タブを開きます。
上部のカードで 新しいワークフロー をクリックし、n8n ワークフロー を選択します。
ワークフロー名と n8n の本番 URL を入力します。
Header authentication を、header name と秘密の header value で設定します。
n8n からの通知 の下では、この n8n ワークフローで実際に構築した項目のみをチェックします: 進捗、承認、および/またはワークフローの終了。
必要に応じて、POST リクエストで送信するフィールドを追加します。
ワークフローを保存します。

3 つの通知オプションはすべて既定でオフです。後から n8n に callback や承認ステップを追加した場合は、AI-School の登録内容も更新してください。これによりダイアログは、開始確認だけを表示すべきか、それとも追加の通知を待ち続けるべきかを判断できます。

フィールド

フィールドは任意です。
各フィールドは 1 つのフィールド名と 1 つのタイプを持ちます。
対応するフィールドタイプは、短いテキスト、長いテキスト、数値、はい/いいえ、日付、単一選択、複数選択です。
単一選択 と 複数選択 では、利用可能な選択肢を追加します。単一選択 はコンパクトなドロップダウンとして表示され、複数選択 はチェックボックスとして表示されます。選択された値は JSON body に送信されます。
必須フィールドは、ワークフローを開始する前に入力されている必要があります。
フィールド名は、n8n に送信される JSON body の key になります。

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

n8n で新しいワークフローを作成します。
最初の node として Webhook を追加します。
この node に正確に Start workflow という名前を付けます。以降の例ではこの名前を使います。
HTTP Method を POST に設定します。
Authentication で Header Auth を選び、Header Auth credential を選択します。
その credential に、AI-School のワークフローと同じ header name と secret value を入力します。
Respond または Response Mode を Immediately に設定します。これでアプリは成功した開始確認をすぐに受け取り、n8n はそのまま続行します。
Webhook node の Production URL を、AI-School の n8n productie-url フィールドにコピーします。/webhook-test/ を含む test-url は使わないでください。
n8n でワークフローを有効化します。

AI-School のデータは n8n では body 配下にあります。そのため統合情報は body.integration の下にあります。Edit Fields、Set、または Code node でこのデータを削除しないでください。以下の例では、常に node Start workflow から直接読み取ります。

JSON body の例

prompt、klantnaam、doelgroepen、datum という名前のフィールドを定義した場合、n8n にはたとえば次の JSON body が届きます。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"
  }
}

callback token は 1 回の実行に対応します。ログ、固定設定、または他のシステムに保存しないでください。

任意: 進捗と完了を返送する

AI-School は n8n が返送した内容のみを表示できます。これらの callbacks は、登録時に Tussentijdse voortgang melden および/または Het einde van de workflow melden を有効にしている場合のみ使用してください。

HTTP Request node の設定

HTTP Request node を追加し、たとえば Meld voortgang と名付けます。
Method を POST に設定します。
URL のところで Expression をクリックします。

次の expression をそのまま貼り付けます。

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

Authentication は None を選択します。次のステップで一時 token を header として追加します。
Send Headers を有効にし、次の 2 つの header を追加します。

Name Value
Authorization Bearer {{ $('Start workflow').first().json.body.integration.callbackToken }}
Content-Type application/json
Send Body を有効にします。
Body Content Type: JSON と Specify Body: Using JSON を選択します。
以下の JSON を JSON フィールドに貼り付けます。

Name	Value
`Authorization`	`Bearer {{ $('Start workflow').first().json.body.integration.callbackToken }}`
`Content-Type`	`application/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."
}

アプリ経由でワークフローをテストしている間に Execute step を選択します。node は status 200 を返すはずです。

この HTTP Request node を、各 status 通知ごとに複製してください。複製ごとに少なくとも eventId、step.id、step.label、message を変更します。

最後の callback の設定

Het einde van de workflow melden が有効な場合、可能なすべてのルートの末尾に最後の callback を配置する必要があります。成功時は type: "completed"、自分で処理するエラー時は type: "failed"、ユーザーがワークフローを拒否した場合は type: "rejected" を使用します。

成功した実行では、body は次のようになります。

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

1 回の実行では、callback ごとに異なる eventId を使用してください。step.label も常に明確なものにしてください。このテキストはユーザーが実行ウィンドウで目にします。

任意: アプリで承認を求める

Wait node の設定

承認が必要な場所に Wait node を追加します。
Resume で On Webhook Call を選択します。
HTTP Method を POST に設定します。
Authentication で Header Auth を選択します。
Start workflow node と同じ Header Auth credential を選びます。
先ほど設定した HTTP Request node のコピーを Wait node の前に配置し、Vraag goedkeuring と名付けます。
この node では同じ動的 URL と headers を使用します。JSON body だけを次の内容に置き換えます。

{
  "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 node に接続します。その後、ユーザーには AI-School 上でボタンが表示されます。秘密の resume-url はブラウザには渡されず、サーバーが安全に選択を Wait node に送ります。

Wait node の後の選択を処理する

Wait node の後に Switch node を追加します。
判定する値として次を使用します。
```
{{ $json.body.decision }}
```
たとえば approve 用のルートと reject 用のルートを作成します。
各ルートの終わりに、適切な completed、rejected、または failed callback を置きます。

選択値には、文字、数字、_、- のみを含めることができます。label には通常の読みやすいテキストを含めてもかまいません。

本番 callback-url の設定

AI-School の本番 callback-url は次のとおりです。

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

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

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

これにより、AI-School は開始のたびに正しい本番 URL を自動的に渡します。上記の固定 URL は、テスト時に expression が AI-School を指しているか確認するためだけに使います。

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

予期しないエラーを返送する

通常の failed callback は、ワークフローが該当する HTTP Request node に到達した場合にのみ機能します。予期しない node エラーに備えて、別途 n8n の中央 Error Workflow も使用してください。

中央 Error Workflow を作成する

n8n で AI-School - fouten terugsturen という名前の別ワークフローを作成します。
Error Trigger node を追加します。
その後に HTTP Request node を追加します。
Method を POST に設定します。

URL に次の固定本番 URL を入力します。

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

Authentication: None を選択します。
Send Headers を有効にし、次を追加します。

Name Value
n8n-handihow-name de geheime standaardwaarde die je van de platformbeheerder ontvangt
Content-Type application/json
Send Body を有効にし、JSON を選択して、次の body を貼り付けます。

Name	Value
`n8n-handihow-name`	de geheime standaardwaarde die je van de platformbeheerder ontvangt
`Content-Type`	`application/json`

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

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

Start workflow の直後には、executionId: "{{ $execution.id }}" を含む少なくとも 1 つの進捗 callback を必ず送ってください。これにより、予期しない n8n エラーがどの実行に属するかアプリが判断できます。

重要な制限

対応しているのは webhook trigger のみです。
対応しているのは本番 webhook URL のみです。
/webhook-test/ を含む test-webhook URL は拒否されます。
対応しているのは POST のみです。
対応しているのは generic header authentication のみです。
header value はアプリケーション内で秘密として扱われます。
callback token と resume URL はサーバー側でのみ処理され、ユーザーから直接参照することはできません。
tenant は、ブラウザから送られた値ではなく、ログイン中のユーザーからサーバー側で決定されます。

問題の解決

404 または webhook 未登録: n8n でワークフローを有効化し、本番 URL を使用してください。
認証エラー: header name と value が両方のシステムで完全に一致しているか確認してください。
データ不足: アプリ内のフィールド名が、n8n が期待する keys と一致しているか確認してください。
n8n にリクエストが届かない: ワークフローが webhook trigger で始まり、POST を使用しているか確認してください。
実行ウィンドウが回り続ける: Het einde van de workflow melden を有効にしている場合、n8n が最後に completed、failed、または rejected callback を送信しているか確認してください。通知を期待していない場合は、登録時の 3 つのオプションをすべてオフにしてください。
進捗が表示されない: 登録時に Tussentijdse voortgang melden が有効になっているか、integration オブジェクトが保持されているか、各 callback に一意の eventId があるか確認してください。
承認ボタンが動作しない: Wait node、resumeUrl、header authentication、そして choices[].value の許可文字を確認してください。

例: 学校サイトへのニュース記事​

この統合は何をするのか？​

AI-School で n8n ワークフローを作成する​

フィールド​

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

JSON body の例​

任意: 進捗と完了を返送する​

HTTP Request node の設定​

最後の callback の設定​

任意: アプリで承認を求める​

Wait node の設定​

Wait node の後の選択を処理する​

本番 callback-url の設定​

予期しないエラーを返送する​

中央 Error Workflow を作成する​

重要な制限​

問題の解決​