n8n 工作流程

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

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

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

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

从短文本生成一段更好的初稿文本，使用一个 LLM 节点和一个与学校语气相符的提示。
用第二个 LLM 节点生成合适的插图，例如使用学校的颜色和易于辨识的插画风格。
将文本和图片整理为博客文章，准备好或直接发布在 WordPress 网站上。

AI-School 与 n8n 的协同工作方式：在 AI-School 中，用户选择工作流并填写所需信息。随后 n8n 执行自动化步骤，确保新闻文章正确地发布在网站上。

这个集成能做什么？

你可以从工作流总览中启动一个 n8n 工作流。仅生产 webhook、POST 和 Header Auth 为必填字段。来自 n8n 的字段和回调可选，并且彼此独立设置。

若工作流没有字段，则 webhook 会立即被调用。
若工作流有字段，则会先打开一个表单。用户填写字段后再通过按钮启动工作流。
所填写的值以 JSON 形式在对 n8n 的 POST 请求中发送。
若没有回传，AI-School 仅确认工作流已启动，且在 n8n 中继续执行。窗口不显示加载动画，可以直接关闭。
若在注册时开启，则工作流可以将中途步骤或结束回传回 AI-School。
若在注册时开启了批准，用户可在 AI-School 中直接进行选择。此后 n8n 将从等待步骤继续执行。

在 AI-School 中创建 n8n 工作流

管理员的注册步骤如下：

进入助手。
打开 工作流。
选择 新建 n8n 工作流。
输入工作流名称和 n8n 生产 URL。
在 Header authentication 中设置一个 header 名称和秘密 header 值。
在 来自 n8n 的回传 下只勾选在该 n8n 工作流中实际构建的部分：进度、批准和/或工作流结束。
如有需要，添加需要在 POST 请求中一起发送的字段。
保存工作流。

三种回传选项默认均为关闭。若之后在 n8n 中添加回调或批准步骤，请同步更新 AI-School 的注册。对话框因此可知它只需显示启动确认，或需要继续等待其他信号。

字段

字段是可选的。
每个字段有一个字段名和一种类型。
支持的字段类型为：简短文本、长文本、数字、是/否、日期、单选和多选。
在单选和多选中添加可用选项。单选以紧凑下拉列表显示；多选显示复选框。所选的值会在 JSON 体中发送。
必填字段在工作流启动前必须填写。
字段名将成为发送到 n8n 的 JSON body 的键。

在 n8n 中创建兼容工作流

在 n8n 中创建一个新工作流。
作为第一节点添加一个 Webhook。
给该节点正确命名为 Start workflow。后文的示例使用该名称。
将 HTTP Method 设置为 POST。
在 Authentication 中选择 Header Auth，并选择一个 Header Auth 凭据。
在该凭据中填入与 AI-School 工作流相同的 header 名称和秘密值。
将 Respond 或 Response Mode 设置为 Immediately。应用将立即收到一个成功的启动确认，同时 n8n 将继续工作。
将 Webhook 节点的 Production URL 复制到 AI-School 的 n8n 生产-url 字段。不使用带有 /webhook-test/ 的测试 URL。
在 n8n 中启用该工作流。

AI-School 的数据在 n8n 中位于 body。集成信息因此位于 body.integration。不要在 Edit Fields、Set 或 Code 节点中删除这些信息。下面的示例总是直接从节点 Start workflow 读取。

JSON body 示例

如果你定义了名为 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"
  }
}

回调令牌仅适用于单次执行。请勿将其存储在日志、固定配置或其他系统中。

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

AI-School 只能显示 n8n 的回传。仅在注册时开启了 “中途进度回传” 和/或 “工作流结束回传” 时才使用这些回调。

设置 HTTP Request 节点

新增一个 HTTP Request 节点，并命名为，例如 回报进度。
将 Method 设置为 POST。
在 URL 处点击 Expression。

粘贴以下表达式：

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

在 Authentication 选择 None。临时令牌将在下一步作为 header 添加。
打开 Send Headers，并添加以下两个 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。该节点应返回状态 200。

为每个状态回传复制此 HTTP Request 节点。每次复制至少修改 eventId、step.id、step.label 和 message。

设置最后的回调

若开启了 “工作流结束回传”，则在每条可能的路径末尾都应有一个最终回调。成功时使用 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 节点

在需要批准的位置添加一个 Wait 节点。
在 Resume 选项中选择 On Webhook Call。
将 HTTP Method 设置为 POST。
在 Authentication 选择 Header Auth。
选择与 “Start workflow” 节点相同的 Header Auth 凭据。
在 Wait 节点之前放置一个此前设置的 HTTP Request 节点的副本，并命名为 Request approval（请求批准）。
在此节点中使用相同的动态 URL 和头信息。仅替换 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" }
    ]
  }
}

将 Request approval 与 Wait 节点连接。用户随后会在 AI-School 中看到按钮。秘密的 resume-url 不会暴露给浏览器；服务器将选择安全地发送给 Wait 节点。

Wait 节点后的选择处理

在 Wait 节点之后添加一个 Switch 节点。
使用要检查的值：
```
{{ $json.body.decision }}
```
为 approve 和 reject 各自创建路由。
每条路由以相应的 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 将为每次启动自动提供正确的生产 URL。上面固定的 URL 仅在测试时用于检查表达式是否指向 AI-School。

调用者 triggerCustomN8nWorkflow、triggerN8nWorkflow 和 resumeN8nWorkflow 由应用自身调用。这些 URL 不需要在 n8n 中配置。

处理意外错误的回传

普通的 failed 回调仅在工作流的相关 HTTP Request 节点到达时才有效。对于意外的节点错误，请使用集中式 n8n Error Workflow。

创建集中式错误工作流

在 n8n 中创建一个名为 AI-School - 错误回传 的独立工作流。
添加一个 Error Trigger 节点。
之后添加一个 HTTP Request 节点。
将 Method 设置为 POST。

在 URL 中填入以下生产 URL：

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

选择 Authentication: None。
打开 Send Headers，并添加：

Name Value
n8n-handihow-name 从平台管理员处获取的秘密默认值
Content-Type application/json
打开 Send Body，选择 JSON，并粘贴以下内容：

Name	Value
`n8n-handihow-name`	从平台管理员处获取的秘密默认值
`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 中选择这一个新的错误工作流。

在 Start workflow 之后立即至少发送一个 progress 回调，包含 executionId: "{{ $execution.id }}"。这有助于应用知道在哪次执行中发生了未预期的 n8n 错误。

重要限制

仅支持 webhook 触发。
仅支持生产 webhook URLs。
测试 webhook URL（带 /webhook-test/）将被拒绝。
仅支持 POST。
仅支持通用 header 验证。
header 值在应用中被视为秘密。
回调令牌和 resume-url 仅由服务器端处理，浏览器无法直接访问。
tenant 由服务器端基于登录用户确定，而非浏览器发送的值。

常见问题

404 或未注册 webhook：在 n8n 中启用工作流并使用生产 URL。
身份验证错误：检查 header 名称和数值在两个系统中是否完全一致。
数据缺失：检查应用中的字段名称是否与 n8n 期望的键一致。
n8n 中无请求：检查工作流是否以 webhook 触发器开始并使用 POST。
执行窗口持续运行：若开启了工作流结束回传，请检查 n8n 是否发送了最后的 completed、failed 或 rejected 回调。若不期望回传，请将三项选项都关闭。
进度不可见：检查注册时是否开启了 中途进度回报，或 integration 对象是否保留，以及每个回调是否具有唯一的 eventId。
批准按钮无效：检查 Wait 节点、resumeUrl、头信息认证以及 choices[].value 中允许的字符。

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

这个集成能做什么？​

在 AI-School 中创建 n8n 工作流​

字段​

在 n8n 中创建兼容工作流​

JSON body 示例​

可选：回传进度与完成状态​

设置 HTTP Request 节点​

设置最后的回调​

可选：在应用中请求批准​

设置 Wait 节点​

Wait 节点后的选择处理​

生产回调 URL 设置​

处理意外错误的回传​

创建集中式错误工作流​

重要限制​

常见问题​