Laravel N8N: A Fluent Client for n8n Automation Workflows

A complete, expressive, and fluent Laravel client for the n8n public REST API and Webhooks Triggering, empowering Laravel developers to interact seamlessly with n8n webhooks, workflows, executions, credentials, tags, users, variables, projects, source control operations and more.

📦 Installation

Install via Composer:

composer require kayedspace/laravel-n8n

Service providers and facades are auto-discovered by Laravel.

⚙️ Configuration

Publish and customize the configuration file:

php artisan vendor:publish --tag=n8n-config

Set environment variables in .env:

N8N_TIMEOUT=120
N8N_THROW=true
N8N_RETRY=3

N8N_API_BASE_URL=https://your-n8n-instance.com/api/v1
N8N_API_KEY=your_api_key

N8N_WEBHOOK_BASE_URL=https://your-n8n-instance.com/webhook
N8N_WEBHOOK_USERNAME=your_webhook_username
N8N_WEBHOOK_PASSWORD=your_webhook_password

🚀 Quick Start

use KayedSpace\N8n\Facades\N8nClient;

// trigger webhook
$webhookTrigger =N8nClient::webhooks()->request("path-to-webhook",$payload);

// List all workflows
$workflows = N8nClient::workflows()->list();


// Retrieve execution status with data
$status = N8nClient::executions()->get($execution['id'], includeData: true);

⚡ Webhooks Trigger

The Webhooks class enables sending HTTP requests to n8n workflow webhook trigger URLs, supporting multiple HTTP verbs ( GET, POST, etc.) and basic authentication (if configured).

basic auth is applied by default if N8N_WEBHOOK_USERNAME, N8N8_WEBHOOK_PASSOWRD are set in the .env file.

Example:

//request a webhook
$webhookTrigger =N8nClient::webhooks()->request("path-to-webhook",$payload);

//request a webhook with custom basic auth credentials
//overwrites values provided on .env` file 
$webhookTrigger =N8nClient::withBasicAuth("custom-username","custom-password")->request("path-to-webhook",$payload);

//request a  webhook without  auth
$webhookTrigger =N8nClient::withoutBasicAuth()->request("path-to-webhook",$payload);

📚 Full API Resource Reference

Below is an exhaustive reference covering every resource and method provided.

🕵 Audit

Method	HTTP Method & Path	Description
`generate(array $additionalOptions = [])`	`POST /audit`	Generate a full audit report based on optional categories or filters

Description: This endpoint performs a security audit of your n8n instance and returns diagnostics grouped by category. It must be invoked by an account with owner privileges.

🔑 Credentials

Method Signature	HTTP Method & Path	Description
`create(array $payload)`	`POST /credentials`	Create a credential using the appropriate type schema.
`list(int $limit = 100, ?string $cursor = null)`	`GET /credentials`	List stored credentials with optional pagination.
`get(string $id)`	`GET /credentials/{id}`	Retrieve details of a specific credential by ID.
`delete(string $id)`	`DELETE /credentials/{id}`	Delete a credential permanently.
`schema(string $typeName)`	`GET /credentials/schema/{typeName}`	Get the schema definition for a credential type.
`transfer(string $id, string $destinationProjectId)`	`PUT /credentials/{id}/transfer`	Move a credential to another project using its ID.

Example:

$schema = N8nClient::credentials()->schema('slackApi');

N8nClient::credentials()->create([
    'name' => 'Slack Token',
    'type' => 'slackApi',
    'data' => [
        'token' => 'xoxb-123456789',
    ]
]);

⏯️ Executions

Method Signature	HTTP Method & Path	Description
`list(array $filters = [])`	`GET /executions`	Retrieve a paginated list of workflow executions. Supports filters such as `status`, `workflowId`, `projectId`, `includeData`, `limit`, `cursor`.
`get(int $id, bool $includeData = false)`	`GET /executions/{id}`	Retrieve detailed information for a specific execution. Optionally include execution data.
`delete(int $id)`	`DELETE /executions/{id}`	Delete an execution record by ID.

Example:

// Get a list of executions filtered by status
$executions = N8nClient::executions()->list(['status' => 'success']);

// Get detailed execution data
$execution = N8nClient::executions()->get(101, true);

// Delete an execution
N8nClient::executions()->delete(101);

🚧 Projects

Method Signature	HTTP Method & Path	Description
`create(array $payload)`	`POST /projects`	Create a new project with name, description, etc.
`list(int $limit = 100, ?string $cursor = null)`	`GET /projects`	Retrieve a paginated list of projects.
`update(string $projectId, array $payload)`	`PUT /projects/{projectId}`	Update project name or metadata. Returns 204 No Content on success.
`delete(string $projectId)`	`DELETE /projects/{projectId}`	Delete a project by ID. Returns 204 No Content on success.
`addUsers(string $projectId, array $relations)`	`POST /projects/{projectId}/users`	Add users to a project with specified roles via the `relations` array.
`changeUserRole(string $projectId, string $userId, string $role)`	`PATCH /projects/{projectId}/users/{userId}`	Change the role of an existing user within a project.
`removeUser(string $projectId, string $userId)`	`DELETE /projects/{projectId}/users/{userId}`	Remove a user from a project.

Example Usage:

// Create a project
$project = N8nClient::projects()->create(['name' => 'DevOps', 'description' => 'CI/CD flows']);

// Add users
N8nClient::projects()->addUsers($project['id'], [
  ['userId' => 'abc123', 'role' => 'member'],
]);

// Promote user role
N8nClient::projects()->changeUserRole($project['id'], 'abc123', 'admin');

// Delete the project
N8nClient::projects()->delete($project['id']);

📝 Source Control

Method Signature	HTTP Method & Path	Description
`pull(array $payload)`	`POST /source-control/pull`	Trigger a pull operation from the connected Git source for all projects.

Example:

$syncStatus = N8nClient::sourceControl()->pull([
    'projectIds' => ['project-1', 'project-2'],
]);

Requires source control integration to be configured in the n8n instance.

🏷️ Tags

Method Signature	HTTP Method & Path	Description
`create(array $payload)`	`POST /tags`	Create a new tag with the given name or properties.
`list(int $limit = 100, ?string $cursor = null)`	`GET /tags`	List all tags with optional pagination using limit/cursor.
`get(string $id)`	`GET /tags/{id}`	Retrieve a single tag by its ID.
`update(string $id, array $payload)`	`PUT /tags/{id}`	Update the name or properties of a specific tag.
`delete(string $id)`	`DELETE /tags/{id}`	Delete a tag permanently by its ID.

Example:

// List all tags
$tags = N8nClient::tags()->list();

// Create a tag
$newTag = N8nClient::tags()->create(['name' => 'marketing']);

// Update a tag
N8nClient::tags()->update($newTag['id'], ['name' => 'marketing-2025']);

// Delete a tag
N8nClient::tags()->delete($newTag['id']);

🙍 Users

Method Signature	HTTP Method & Path	Description
`list(array $filters = [])`	`GET /users`	List users with optional filters: `limit`, `cursor`, `includeRole`, `projectId`.
`create(array $userPayloads)`	`POST /users`	Create (invite) one or more users by providing user objects.
`get(string $idOrEmail, bool $includeRole = false)`	`GET /users/{idOrEmail}`	Get a user by ID or email. Optionally include role.
`delete(string $idOrEmail)`	`DELETE /users/{idOrEmail}`	Delete a user by ID or email.
`changeRole(string $idOrEmail, string $newRoleName)`	`PATCH /users/{idOrEmail}/role`	Change the user's role to the new role name.

Example:

//list users 
N8nClient::users()->list();

// Invite users
N8nClient::users()->create([
  ['email' => '[email protected]', 'role' => 'member']
]);

// Promote to admin
N8nClient::users()->changeRole('[email protected]', 'admin');

// delete a user
N8nClient::users()->delete('[email protected]');

🔠 Variables

Method Signature	HTTP Method & Path	Description
`create(array $payload)`	`POST /variables`	Create a new variable with a key-value pair.
`list(int $limit = 100, ?string $cursor = null)`	`GET /variables`	List variables with optional pagination using limit and cursor.
`update(string $id, array $payload)`	`PUT /variables/{id}`	Update the value of an existing variable.
`delete(string $id)`	`DELETE /variables/{id}`	Permanently delete a variable.

Example:

// list all variable
N8nClient::variables()->list()

// Create a new variable
N8nClient::variables()->create(['key' => 'ENV_MODE', 'value' => 'production']);

// Update the variable
N8nClient::variables()->update('ENV_MODE', ['value' => 'staging']);

// Delete the variable
N8nClient::variables()->delete('ENV_MODE');

🔄 Workflows

Method Signature	HTTP Method & Path	Description
`create(array $payload)`	`POST /workflows`	Create a new workflow using a flow definition.
`list(array $filters = [])`	`GET /workflows`	List workflows with optional filters: `active`, `tags`, `projectId`, etc.
`get(string $id, bool $excludePinnedData = false)`	`GET /workflows/{id}`	Retrieve a specific workflow; optionally exclude pinned node data.
`update(string $id, array $payload)`	`PUT /workflows/{id}`	Update the workflow definition.
`delete(string $id)`	`DELETE /workflows/{id}`	Delete the specified workflow.
`activate(string $id)`	`POST /workflows/{id}/activate`	Activate the workflow.
`deactivate(string $id)`	`POST /workflows/{id}/deactivate`	Deactivate the workflow.
`transfer(string $id, string $destinationProjectId)`	`PUT /workflows/{id}/transfer`	Move a workflow to a different project.
`tags(string $id)`	`GET /workflows/{id}/tags`	Get all tags associated with the workflow.
`updateTags(string $id, array $tagIds)`	`PUT /workflows/{id}/tags`	Update the list of tag IDs for a workflow.

Example:

// Create and  a workflow
$workflow = N8nClient::workflows()->create([
    'name'   => 'Daily Report',
    'nodes'  => [...], // full JSON definition
    'connections' => [...],
]);

//Activate the workflow
N8nClient::workflows()->activate($workflow['id']);

//Deactivate the workflow
N8nClient::workflows()->deactivate($workflow['id']);

//update the workflow.
N8nClient::workflows()->update($workflow['id'],[...]);

//Move a workflow to a different project.
N8nClient::workflows()->transfer($workflow['id'],$destinationProjectId);

//Get all tags associated with the workflow.
N8nClient::workflows()->tags($workflow['id']);

// update workflow tags.
N8nClient::workflows()->updateTags($workflow['id'],[...]);

//Delete the workflow.
N8nClient::workflows()->delete($workflow['id']);

🤝 Contributing

Contributions are welcome! If you have a feature request, bug report, or improvement:

Fork the repository
Create a topic branch: Choose the prefix that matches the purpose of your work:
- feature/your-description – new functionality
- bugfix/your-description – fix for an existing issue
- hotfix/your-description – urgent production fix
Run Laravel Pint to ensure code style is consistentcomposer pint
Add or update tests and make sure they pass composer test
Commit your changesgit commit -am "Add: my awesome addition"
Push to your branch git push origin feature/my-awesome-addition
Open a pull request

Please adhere to laravel pint and include tests where applicable.

🛠 Support

If you encounter any issues or have questions:

Open an issue in the GitHub repository
Use Discussions for non-bug topics or feature proposals
Pull requests are always welcome for fixes and improvements

📄 License

This package is open-sourced software licensed under the MIT license.

Name		Name	Last commit message	Last commit date
Latest commit History 82 Commits
.github		.github
config		config
src		src
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENCE		LICENCE
README.md		README.md
composer.json		composer.json
phpstan.neon		phpstan.neon
phpunit.xml.dist		phpunit.xml.dist
pint.json		pint.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

Laravel N8N: A Fluent Client for n8n Automation Workflows

Table of Contents

📦 Installation

⚙️ Configuration

🚀 Quick Start

⚡ Webhooks Trigger

📚 Full API Resource Reference

🕵 Audit

🔑 Credentials

⏯️ Executions

🚧 Projects

📝 Source Control

🏷️ Tags

🙍 Users

🔠 Variables

🔄 Workflows

🤝 Contributing

🛠 Support

📄 License

About

Uh oh!

Releases 3

Uh oh!

Contributors 3

Languages

License

kayedspace/laravel-n8n

Folders and files

Latest commit

History

Repository files navigation

Laravel N8N: A Fluent Client for n8n Automation Workflows

Table of Contents

📦 Installation

⚙️ Configuration

🚀 Quick Start

⚡ Webhooks Trigger

📚 Full API Resource Reference

🕵 Audit

🔑 Credentials

⏯️ Executions

🚧 Projects

📝 Source Control

🏷️ Tags

🙍 Users

🔠 Variables

🔄 Workflows

🤝 Contributing

🛠 Support

📄 License

About

Topics

Resources

License

Code of conduct

Uh oh!

Stars

Watchers

Forks

Releases 3

Uh oh!

Contributors 3

Languages