External hooks

External hooks let you run custom code whenever n8n performs a specific operation. Use them to log data, change data, or forbid an action by throwing an error.

There are two types:

• Backend hooks: run server-side, registered using the EXTERNAL_HOOK_FILES environment variable.
• Frontend hooks: run in the browser, loaded with a script tag.

For the environment variables used to register hooks, refer to External hooks environment variables.

Backend hooks

Available hooks

Registering hooks

Set hooks by registering a hook file that contains the hook functions. To register a hook, set the environment variable EXTERNAL_HOOK_FILES.

You can set the variable to a single file:

EXTERNAL_HOOK_FILES=/data/hook.js

Or to contain multiple files separated by a colon:

EXTERNAL_HOOK_FILES=/data/hook1.js:/data/hook2.js

Hook files

Hook files are regular JavaScript files that have the following format:

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.'
                    );
                }
            }
        ]
    }
}

Hook examples

Block workflow execution if a required tag is missing

Please note: the workflowContext argument is supplied to workflow.preExecute hooks from n8n 2.23.0. Refer to Workflow hook context for the full list of hooks that receive it and from which version.

Use workflow.preExecute to abort execution when a workflow doesn't have a required tag:

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

Some workflow hooks receive a workflowContext argument, an instance of WorkflowHookContextService. It exposes helper methods you can call inside the hook function.

The context provides these methods:

This example uses resolveIsTriggerNodeType to block activating a workflow that doesn't contain a trigger node:

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

Some workflow lifecycle hooks receive an actor argument, a minimal projection of the user who performed the operation. Use it to attribute the action, for example to allow or reject an operation based on the user's identity or role.

The actor object has these properties:

This example uses actor to log who deleted a workflow:

module.exports = {
	workflow: {
		delete: [
			async function (workflowId, actor) {
				console.log(`Workflow ${workflowId} deleted by ${actor?.email} (${actor?.role})`);
			},
		],
	},
};

Hook functions

A hook or a hook file can contain multiple hook functions, with all functions executed one after another.

If the parameters of the hook function are objects, it's possible to change the data of that parameter to change the behavior of n8n.

You can also access the database in any hook function using this.dbCollections (refer to the code sample in Hook files above).

Frontend external hooks

Like backend external hooks, it's possible to define external hooks in the frontend code that get executed by n8n whenever a user performs a specific operation. You can use them, for example, to log data and change data.

Available hooks

Registering frontend hooks

You can set hooks by loading the hooks script on the page. One way to do this is by creating a hooks file in the project and adding a script tag in your editor-ui/public/index.html file:

<script src="frontend-hooks.js"></script>

Frontend hook files

Frontend external hook files are regular JavaScript files which have the following format:

window.n8nExternalHooks = {
  nodeView: {
    mount: [
      function (store, meta) {
        // do something
      },
    ],
    createNodeActiveChanged: [
      function (store, meta) {
        // do something
      },
      function (store, meta) {
        // do something else
      },
    ],
    addNodeButton: [
      function (store, meta) {
        // do something
      },
    ],
  },
};

Frontend hook functions

You can define multiple hook functions per hook. n8n calls each hook function with the following arguments:

• store: The Vuex store object. You can use this to change or get data from the store.
• metadata: The object that contains any data provided by the hook. To see what's passed, search for the hook in the editor-ui package.