n8n 工作流

AI-School 可以通过生产 webhook 启动 n8n 工作流。当你想在 AI-School 之外启动自动化流程时，这很有用，例如创建任务、更新 CRM 记录、启动报告流程，或把表单数据传递到其他系统。

示例：学校网站上的新闻文章

假设学校创建了一个 n8n 工作流，用于在学校的 WordPress 网站上发布新闻文章。在 AI-School 中，你只需填写一小段文字，例如关于项目周、运动日或开放日的几句话。然后你就可以用这段文字在 n8n 中启动工作流。

随后，n8n 工作流可以例如：

1. 使用一个 LLM 节点和适合学校语气的提示词，将简短文本整理成一篇体面的草稿。
2. 使用第二个 LLM 节点生成合适的插图，例如使用学校配色并采用易于识别的插画风格。
3. 将文本和图片作为博客文章准备好或发布到 WordPress 网站上。

这样 AI-School 和 n8n 就能协同工作：在 AI-School 中，用户选择工作流并填写所需信息；随后 n8n 执行自动化步骤，确保新闻文章整洁地出现在网站上。

这个集成做什么？

你可以从工作流概览中启动一个 n8n 工作流。只有生产 webhook、POST 和 Header Auth 是必需的。来自 n8n 的字段和回调都是可选的，并且可以彼此独立配置。

• 如果工作流没有字段，则会立即调用 webhook。
• 如果工作流有字段，则会先打开一个表单。用户填写字段后，再点击按钮启动工作流。
• 填写的值会作为 JSON 通过 POST 请求发送到 n8n webhook。
• 如果没有回调，AI-School 只会确认工作流已启动，后续会在 n8n 中继续运行。窗口不会显示 spinner，可立即关闭。
• 如果在注册时启用了此选项，工作流可以将中间步骤或结束状态回传给 AI-School。
• 如果在注册时启用了审批，用户可以直接在 AI-School 中做出选择。之后 n8n 会从等待步骤继续执行。

在 AI-School 中创建 n8n 工作流

管理员按以下方式注册工作流：

1. 前往 助手。
2. 打开 工作流助手 选项卡。
3. 在顶部卡片中点击 新工作流，并选择 n8n 工作流。
4. 填写工作流名称和 n8n 生产 URL。
5. 使用 header name 和机密 header value 配置 Header authentication。
6. 在 来自 n8n 的回调 下，只勾选该 n8n 工作流中真正已实现的部分：进度、审批和/或工作流结束。
7. 如有需要，添加要在 POST 请求中发送的字段。
8. 保存工作流。

这三种回调选项默认都关闭。如果你之后在 n8n 中添加了回调或审批步骤，也要更新 AI-School 中的注册信息。这样对话框就能知道是只需显示启动确认，还是需要继续等待后续信号。

字段

• 字段是可选的。
• 每个字段只有一个字段名和一种类型。
• 支持的字段类型有短文本、长文本、数字、是/否、日期、单选和多选。
• 对于 单选 和 多选，需要添加可用选项。单选 会显示为紧凑的下拉列表；多选 会显示复选框。所选值会作为 JSON body 发送。
• 必填字段必须填写后才能启动工作流。
• 字段名会成为发送到 n8n 的 JSON body 中的 key。

在 n8n 中创建兼容工作流

1. 在 n8n 中创建一个新工作流。
2. 添加一个 Webhook 节点作为第一个节点。
3. 将该节点准确命名为 Start workflow。后面的示例会使用这个名称。
4. 将 HTTP Method 设为 POST。
5. 在 Authentication 中选择 Header Auth，并选择一个 Header Auth credential。
6. 在该 credential 中填写与 AI-School 中工作流相同的 header 名称和机密值。
7. 将 Respond 或 Response Mode 设为 Immediately。这样应用会立即收到成功启动确认，而 n8n 会继续执行。
8. 将 Webhook 节点的 Production URL 复制到 AI-School 中的 n8n 生产 url 字段。不要使用带 /webhook-test/ 的测试 url。
9. 在 n8n 中激活该工作流。

来自 AI-School 的数据在 n8n 中位于 body 下。因此集成数据位于 body.integration 下。不要在 Edit Fields、Set 或 Code 节点中删除这些数据。下面的示例都会直接从节点 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 只对应一次执行。不要将其保存在日志、固定配置或其他系统中。

可选：回传进度和完成状态

AI-School 只能展示 n8n 回传的内容。只有在注册时启用了 Tussentijdse voortgang melden 和/或 Het einde van de workflow melden 时，才使用这些回调。

配置 HTTP Request 节点

1. 添加一个 HTTP Request 节点，并将其命名为例如 Meld voortgang。

2. 将 Method 设为 POST。

3. 在 URL 旁点击 Expression。

4. 精确粘贴以下表达式：

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

5. 在 Authentication 中选择 None。临时 token 会在下一步作为 header 添加。

6. 打开 Send Headers，并添加这两个 header：

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

7. 打开 Send Body。

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"。

成功执行时，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"
  }
}

在同一次执行中，每个回调都要使用不同的 eventId。还要始终使用清晰的 step.label：用户会在执行窗口中看到这段文字。

可选：在应用中请求审批

配置 Wait 节点

1. 在需要审批的位置添加一个 Wait 节点。
2. 在 Resume 中选择 On Webhook Call。
3. 将 HTTP Method 设为 POST。
4. 在 Authentication 中选择 Header Auth。
5. 选择与节点 Start workflow 相同的 Header Auth credential。
6. 在 Wait 节点之前放置一个之前配置好的 HTTP Request 节点副本，并将其命名为 Vraag goedkeuring。
7. 在该节点中使用相同的动态 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 节点连接起来。之后用户会在 AI-School 中看到按钮。机密 resume-url 不会提供给浏览器；服务器会安全地将选择发送到 Wait 节点。

在 Wait 节点后处理选择

1. 在 Wait 节点后添加一个 Switch 节点。

2. 将要检查的值设为：

   {{ $json.body.decision }}

3. 例如，为 approve 创建一条路由，为 reject 创建一条路由。

4. 让每条路由都以合适的 completed、rejected 或 failed 回调结束。

一个选择值只能包含字母、数字、_ 和 -。但 label 可以包含普通可读文本。

设置生产 callback-url

AI-School 的生产 callback-url 是：

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

不要把这个 URL 作为固定文本粘贴到每个 callback 节点中。在 HTTP Request 节点的 URL 字段中选择 Expression，并使用：

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

这样 AI-School 会在每次启动时自动提供正确的生产 url。上面的固定 URL 仅用于测试时检查表达式是否指向 AI-School。

应用会自行调用 triggerCustomN8nWorkflow、triggerN8nWorkflow 和 resumeN8nWorkflow。这些 URL 你无需在 n8n 中设置。

回传意外错误

普通的 failed 回调只有在工作流执行到对应的 HTTP Request 节点时才会生效。对于意外的节点错误，还应使用一个中央 n8n Error Workflow。

创建中央 Error Workflow

1. 在 n8n 中创建一个独立工作流，名称为 AI-School - fouten terugsturen。

2. 添加一个 Error Trigger 节点。

3. 然后添加一个 HTTP Request 节点。

4. 将 Method 设为 POST。

5. 在 URL 中填写这个固定的生产 URL：

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

6. 选择 Authentication: None。

7. 打开 Send Headers，并添加：

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

8. 打开 Send Body，选择 JSON，并粘贴以下 body：

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

9. 激活 Error Workflow。
10. 打开普通工作流的设置，并在 Error Workflow 中选择这个新的 Error Workflow。

在 Start workflow 之后，始终至少发送一条带有 executionId: "{{ $execution.id }}" 的进度回调。这样应用就知道某个意外的 n8n 错误属于哪次执行。

重要限制

• 仅支持 webhook 触发器。
• 仅支持生产 webhook URL。
• 带 /webhook-test/ 的测试 webhook URL 会被拒绝。
• 仅支持 POST。
• 仅支持通用 header authentication。
• 应用会将 header value 视为机密。
• callback token 和 resume-url 只在服务器端处理，不会直接提供给用户。
• tenant 由服务器端根据已登录用户确定，而不是由浏览器发送的值决定。

故障排查

• 404 或 webhook 未注册：在 n8n 中激活工作流，并使用生产 URL。
• 认证错误：检查两个系统中的 header name 和 value 是否完全一致。
• 数据缺失：检查应用中的字段名是否与 n8n 期望的 key 一致。
• n8n 中没有请求：检查工作流是否以 webhook trigger 开始，并使用 POST。
• 执行窗口一直转圈：如果你启用了 Het einde van de workflow melden，请检查 n8n 是否发送了最后的 completed、failed 或 rejected 回调。如果你不期望任何回调，请在注册时关闭这三个选项。
• 没有看到进度：检查注册时是否已开启 Tussentijdse voortgang melden，integration 对象是否保留，以及每个回调是否有唯一的 eventId。
• 审批按钮无效：检查 Wait 节点、resumeUrl、header authentication，以及 choices[].value 中允许的字符。