外部挂钩
外部钩子让你在 n8n 执行特定操作时运行自定义代码,可用于记录数据、修改数据,或通过抛出错误禁止某项操作。
有两种类型:
- Backend hooks 后端钩子:在服务器端运行,通过
EXTERNAL_HOOK_FILES环境变量注册。 - Frontend hooks 前端钩子:在浏览器中运行,通过 script 标签加载。
用于注册hooks的环境变量请参考外部hooks环境变量。
后端挂钩
可用挂钩
| 钩子 | 参数 | 描述 |
|---|---|---|
credentials.create |
[credentialData: ICredentialsDb] |
创建新凭据前调用。可用于限制凭据数量。 |
credentials.delete |
[id: credentialId] |
删除凭据前调用。 |
credentials.update |
[credentialData: ICredentialsDb] |
n8n 保存现有凭据前调用。 |
frontend.settings |
[frontendSettings: IN8nUISettings] |
n8n 启动时调用。例如,可覆盖前端数据(如显示的 OAuth URL)。 |
n8n.ready |
[app: App] |
n8n 就绪后调用一次。例如,可注册自定义 API 端点。 |
n8n.stop |
n8n 进程停止时调用,可用于保存部分进程数据。 | |
oauth1.authenticate |
[oAuthOptions: clientOAuth1.Options, oauthRequestData: {oauth_callback: string}] |
OAuth1 身份验证前调用,可用于覆盖 OAuth 回调 URL。 |
oauth2.callback |
[oAuth2Parameters: {clientId: string, clientSecret: string \| undefined, accessTokenUri: string, authorizationUri: string, redirectUri: string, scopes: string[]}] |
OAuth2 回调时调用,可用于覆盖 OAuth 回调 URL。 |
workflow.activate |
[workflowData: IWorkflowBase, workflowContext: WorkflowHookContextService, actor?: WorkflowLifecycleHookActor] |
激活工作流前调用,可用于限制 active workflows 的数量。有关 workflowContext 参数,请参阅 Workflow hook context;有关 actor 参数,请参阅 Workflow lifecycle hook actor。 |
workflow.afterCreate |
[workflowData: IWorkflowBase, workflowContext: WorkflowHookContextService, actor?: WorkflowLifecycleHookActor] |
创建工作流后调用。有关 workflowContext 参数,请参阅 Workflow hook context;有关 actor 参数,请参阅 Workflow lifecycle hook actor。 |
workflow.afterDelete |
[workflowId: string, actor?: WorkflowLifecycleHookActor] |
删除工作流后调用。有关 actor 参数,请参阅 Workflow lifecycle hook actor。 |
workflow.afterUpdate |
[workflowData: IWorkflowBase, workflowContext: WorkflowHookContextService, actor?: WorkflowLifecycleHookActor] |
保存现有工作流后调用。有关 workflowContext 参数,请参阅 Workflow hook context;有关 actor 参数,请参阅 Workflow lifecycle hook actor。 |
workflow.create |
[workflowData: IWorkflowBase, workflowContext: WorkflowHookContextService, actor?: WorkflowLifecycleHookActor] |
创建工作流前调用,可用于限制已保存工作流的数量。有关 workflowContext 参数,请参阅 Workflow hook context;有关 actor 参数,请参阅 Workflow lifecycle hook actor。 |
workflow.deactivate |
[workflowData: IWorkflowBase, workflowContext: WorkflowHookContextService, actor?: WorkflowLifecycleHookActor] |
停用工作流前调用,此时 active 仍为 true。抛出错误可中止停用并保持工作流处于 active 状态。自 n8n 2.33.1 起可用。有关 workflowContext 参数,请参阅 Workflow hook context;有关 actor 参数,请参阅 Workflow lifecycle hook actor。 |
workflow.delete |
[workflowId: string, actor?: WorkflowLifecycleHookActor] |
删除工作流前调用。有关 actor 参数,请参阅 Workflow lifecycle hook actor。 |
workflow.postExecute |
[fullRunData: IRun \| undefined, workflowData: IWorkflowBase, executionId: string, workflowContext: WorkflowHookContextService] |
工作流执行后调用。有关 workflowContext 参数,请参阅 Workflow hook context。 |
workflow.preExecute |
[workflow: Workflow, mode: WorkflowExecuteMode, workflowContext: WorkflowHookContextService] |
工作流执行前调用,可用于统计或限制工作流执行次数。如果钩子抛出错误,n8n 不会创建执行记录。在 n8n 3.0.0 之前,可设置 N8N_PRE_EXECUTE_ERROR_CREATES_EXECUTION=true,使钩子抛错时仍创建失败的执行;n8n 3.0.0 移除了该变量。有关 workflowContext 参数,请参阅 Workflow hook context(自 n8n 2.23.0 起可用)。 |
workflow.update |
[workflowData: IWorkflowBase, workflowContext: WorkflowHookContextService, actor?: WorkflowLifecycleHookActor] |
保存现有工作流前调用。有关 workflowContext 参数,请参阅 Workflow hook context;有关 actor 参数,请参阅 Workflow lifecycle hook actor。 |
workflow.afterArchive |
[workflowId: string, actor?: WorkflowLifecycleHookActor] |
归档工作流后调用。有关 actor 参数,请参阅 Workflow lifecycle hook actor。 |
workflow.afterUnarchive |
[workflowId: string, actor?: WorkflowLifecycleHookActor] |
从归档中恢复工作流后调用。有关 actor 参数,请参阅 Workflow lifecycle hook actor。 |
注册钩子
通过注册包含钩子函数的钩子文件来设置钩子。要注册钩子,请设置 EXTERNAL_HOOK_FILES 环境变量。
您可以将变量设置为单个文件:
EXTERNAL_HOOK_FILES=/data/hook.js
或包含用冒号分隔的多个文件:
EXTERNAL_HOOK_FILES=/data/hook1.js:/data/hook2.js
挂钩文件
钩子文件是具有以下格式的常规 JavaScript 文件:
module.exports = {
"frontend": {
"settings": [
async function (settings) {
settings.oauthCallbackUrls.oauth1 = 'https://n8n.example.com/oauth1/callback';
settings.oauthCallbackUrls.oauth2 = 'https://n8n.example.com/oauth2/callback';
}
]
},
"workflow": {
"activate": [
async function (workflowData) {
const activeWorkflows = await this.dbCollections.Workflow.count({ active: true });
if (activeWorkflows > 1) {
throw new Error(
'Active workflow limit reached.'
);
}
}
]
}
}
挂钩示例
如果缺少所需标签,则阻止工作流程执行
请注意:workflowContext 参数自 n8n 2.23.0 起提供给 workflow.preExecute hooks。有关接收该参数的完整 hooks 列表及其可用版本,请参阅 Workflow hook context。
使用 workflow.preExecute 在工作流缺少必需标签时中止执行:
module.exports = {
workflow: {
preExecute: [
async function (workflow, mode, workflowContext) {
const requiredTag = 'exampleTag';
const workflowTags = await workflowContext.getWorkflowTags(workflow.id);
if (!workflowTags.includes(requiredTag)) {
throw new Error(`Workflow is missing required tag "${requiredTag}", aborting`);
}
},
],
},
};
Workflow hook context
部分 workflow hooks 会接收 workflowContext 参数,它是 WorkflowHookContextService 的实例。你可以在 hook function 中调用它暴露的 helper methods。
提示
自 n8n 2.23.0 起可用
n8n 会将 workflowContext 传递给 workflow.preExecute hook。
提示
自 n8n 2.33.1 起可用
n8n 会将 workflowContext 传递给 workflow.create、workflow.afterCreate、workflow.activate、workflow.deactivate、workflow.update、workflow.afterUpdate 和 workflow.postExecute hooks。
context 提供以下 methods:
| Method | Returns | Description 描述 |
|---|---|---|
getWorkflowTags(workflowId: string) |
Promise<string[]> |
返回指定 workflow 上附加的 tags 名称。 |
resolveIsTriggerNodeType(type: string, typeVersion?: number) |
boolean |
如果给定 node type 是 trigger,则返回 true。type 是完整 node type 名称,例如 n8n-nodes-base.manualTrigger。typeVersion 默认为最新注册版本。当 n8n 无法解析 node type(例如实例上未注册该类型)时返回 false。 |
以下示例使用 resolveIsTriggerNodeType 阻止激活不包含 trigger node 的 workflow:
module.exports = {
workflow: {
activate: [
async function (workflowData, workflowContext) {
const hasTrigger = workflowData.nodes.some((node) =>
workflowContext.resolveIsTriggerNodeType(node.type, node.typeVersion),
);
if (!hasTrigger) {
throw new Error('Workflow must contain a trigger node, aborting activation');
}
},
],
},
};
Workflow lifecycle hook actor
部分 workflow lifecycle hooks 会接收 actor 参数,它是执行该操作的用户的最小投影。可使用它标记 action 来源,例如根据用户 identity 或 role 允许或拒绝某个操作。
提示
自 n8n 2.33.1 起可用
n8n 会将 actor 传递给 workflow.create、workflow.afterCreate、workflow.activate、workflow.deactivate、workflow.update、workflow.afterUpdate、workflow.delete、workflow.afterDelete、workflow.afterArchive 和 workflow.afterUnarchive hooks。该参数是可选的;当 n8n 无法确定执行操作的用户时,可能为 undefined。
actor object 包含以下 properties:
| Property | Type | Description 描述 |
|---|---|---|
id |
string |
用户的唯一 ID。 |
email |
string \| null |
用户 email address。可以为 null,例如用户已被邀请但尚未完成设置时。 |
firstName |
string \| null |
用户名。可以为 null,例如用户已被邀请但尚未完成设置时。 |
lastName |
string \| null |
用户姓氏。可以为 null,例如用户已被邀请但尚未完成设置时。 |
role |
string |
用户 role slug,例如 global:admin。可选。 |
以下示例使用 actor 记录是谁删除了 workflow:
module.exports = {
workflow: {
delete: [
async function (workflowId, actor) {
console.log(`Workflow ${workflowId} deleted by ${actor?.email} (${actor?.role})`);
},
],
},
};
钩子函数
一个钩子或钩子文件可以包含多个钩子函数,所有函数依次执行。
如果钩子函数的参数是对象,则可以更改该参数的数据以更改 n8n 的行为。
你也可以在任何钩子函数中通过 this.dbCollections 访问数据库(参见上文 钩子文件 中的代码示例)。
前端外部挂钩
与后端外部钩子一样,可以在前端代码中定义外部钩子,当用户执行特定操作时由 n8n 执行。您可以使用它们,例如,记录数据和更改数据。
可用挂钩
| 钩子 | 描述 |
|---|---|
credentialsEdit.credentialTypeChanged |
现有凭据类型变更时调用。 |
credentials.create |
有人创建新凭据时调用。 |
credentialsList.dialogVisibleChanged |
|
dataDisplay.nodeTypeChanged |
|
dataDisplay.onDocumentationUrlClick |
有人点击帮助文档链接时调用。 |
execution.open |
打开现有执行时调用。 |
executionsList.openDialog |
有人从「工作流执行」列表中选择某次执行时调用。 |
expressionEdit.itemSelected |
|
expressionEdit.dialogVisibleChanged |
|
nodeCreateList.filteredNodeTypesComputed |
|
nodeCreateList.nodeFilterChanged |
有人更改节点面板筛选条件时调用。 |
nodeCreateList.selectedTypeChanged |
|
nodeCreateList.mounted |
|
nodeCreateList.destroyed |
|
nodeSettings.credentialSelected |
|
nodeSettings.valueChanged |
|
nodeView.createNodeActiveChanged |
|
nodeView.addNodeButton |
|
nodeView.mount |
|
pushConnection.executionFinished |
|
showMessage.showError |
|
runData.displayModeChanged |
|
workflow.activeChange |
|
workflow.activeChangeCurrent |
|
workflow.afterUpdate |
有人更新现有工作流时调用。 |
workflow.open |
|
workflowRun.runError |
|
workflowRun.runWorkflow |
工作流执行时调用。 |
workflowSettings.dialogVisibleChanged |
|
workflowSettings.saveSettings |
有人保存工作流设置时调用。 |
注册前端钩子
您可以通过在页面上加载钩子脚本来设置钩子。一种方法是在项目中创建钩子文件并在您的 editor-ui/public/index.html 文件中添加脚本标签:
<script src="frontend-hooks.js"></script>
前端挂钩文件
前端外部钩子文件是具有以下格式的常规 JavaScript 文件:
window.n8nExternalHooks = {
nodeView: {
mount: [
function (store, meta) {
// 做某事
},
],
createNodeActiveChanged: [
function (store, meta) {
// 做某事
},
function (store, meta) {
// 做其他事
},
],
addNodeButton: [
function (store, meta) {
// 做某事
},
],
},
};
前端钩子函数
每个钩子可定义多个钩子函数。n8n 使用以下参数调用每个钩子函数:
store:Vuex 存储对象。您可以使用它来更改或从存储中获取数据。metadata:包含钩子提供的任何数据的对象。要查看传递的内容,请在editor-ui包中搜索钩子。