# n8n Connector for Workflow Automation > A two-way bridge between Odoo and n8n: record events fire HMAC-signed webhooks, and a guarded inbound endpoint lets workflows write back. - **What it is:** A two-way bridge between Odoo and n8n: record events fire HMAC-signed webhooks, and a guarded inbound endpoint lets workflows write back. - **For:** Extra Tools - **Odoo versions:** 16.0, 17.0, 18.0, 19.0, 20.0 - Community and Enterprise - **Runs on:** Odoo.sh or Odoo you host yourself - not Odoo Online, which accepts no third-party apps - **Price:** 89 EUR, one-time, on the Odoo Apps Store - **Technical name:** bambooforge_n8n_connector - **Run for real:** Tested for real against a current n8n release: 4 workflows read through the Public API with 0 errors, and a workflow created through the API arrived in Odoo on the next sync. - **Not for:** The connector reads workflows and executions from your n8n server and writes the corresponding Odoo n8n.workflow / n8n.execution records. It never writes to n8n. The API key and webhook secret are stored in admin-only fields.; In scope today: read-only import of workflows and executions, scheduled reconciliation, field mapping, schema introspection, dry-run, validation, rollback snapshots and a multi-step flow engine.; Out of scope: any write-back to n8n (creating/activating/running workflows), inbound change webhooks, and timestamp-based incremental list filtering on the n8n API (v1 lists by cursor pagination; reconciliation re-lists and queues the delta). - **Manual:** https://docs.bambooforge.dev/bambooforge_n8n_connector/ - **Live demo:** https://demo20.bambooforge.dev/odoo/action-bambooforge_n8n_connector.action_n8n_control_tower - **Store page:** https://apps.odoo.com/apps/modules/20.0/bambooforge_n8n_connector - **Manual last updated:** 2026-10-15 --- # n8n Connector for Workflow Automation A read-only bridge from your n8n automation server into Odoo 20: it imports your n8n **workflows** and their **executions** so you can monitor your automations — which workflows are active, how many nodes and triggers they have, and whether their recent runs succeeded, failed, are running or waiting — without leaving Odoo. The connector never writes back to n8n. This page is the complete manual. If you follow it top to bottom you can install, connect, run your first import, automate it, and fix the common issues **without contacting support**. ## Overview The connector pulls data from the n8n public API (`X-N8N-API-KEY` auth, cursor pagination) into dedicated Odoo models. It is **import-first and pull-based**: every remote call is a read, and nothing is ever pushed back to n8n. Direction of sync: **Odoo ← n8n** (read-only monitoring; one-way import). It covers two entities: - **Workflows** — imported into **n8n Connector ▸ Imported Data ▸ Workflows** (model `n8n.workflow`). Each record mirrors the n8n workflow shape: name, the *Active in n8n* flag, node count, trigger count, comma-joined tag names, and the created/updated timestamps from n8n. - **Executions** — imported into **n8n Connector ▸ Imported Data ▸ Executions** (model `n8n.execution`). Each record mirrors an n8n run: status (Success, Error, Running, Waiting, Unknown), mode (manual / trigger / webhook / …), the *Finished* flag, started/stopped timestamps, and a best-effort link to the parent workflow once that workflow has also been imported. Every remote call goes through a queue: nothing is written to Odoo until a job runs, jobs retry with back-off on transient failures, and a circuit breaker pauses an instance that keeps failing. ## Tested against the real thing Automated tests run against a bundled mock on every release; the line below is the part no mock can give you - the connector pointed at the real platform, with real records. Tested for real against a current n8n release: 4 workflows read through the Public API with 0 errors, and a workflow created through the API arrived in Odoo on the next sync. ## Requirements - **Odoo**: 20.0, Community or Enterprise. - **n8n**: any n8n server that exposes the **public REST API** at `/api/v1` with `workflows` and `executions` endpoints (self-hosted or n8n Cloud). The server must be reachable from the Odoo server. - **Python**: no extra libraries beyond a standard Odoo 20 install. - **Odoo access**: any internal user can use the connector screens. The n8n API key and webhook secret are stored in system-only fields, so only the **Settings / Administration** user can read or change them. - **Network**: outbound HTTPS from Odoo to your n8n server. By default the connector refuses internal/loopback/private hosts as an SSRF safeguard (see *Safety features*). ## Installation 1. Copy `bambooforge_n8n_connector` into your Odoo addons path. 2. Restart the Odoo service. 3. Open **Apps**, click **Update Apps List**, search for *n8n*, and press **Activate / Install**. Dependencies (*base*, *mail*) install automatically. No n8n server is required to evaluate the connector: a mock n8n API ships inside the module, so you can install, explore and run the full import flow against sample workflows and executions before pointing it at a real n8n instance. ## Step 1 — Create an n8n API key The connector authenticates with a single n8n API key, sent on every request as the `X-N8N-API-KEY` header. There is no OAuth and no token exchange. In your n8n instance: 1. Open **Settings ▸ n8n API**. 2. Click **Create an API key**. 3. Give the key a label (e.g. `Odoo`) and create it. 4. Copy the key shown — it is displayed once. This is the value you paste into Odoo in Step 2. A read scope is sufficient: the connector only ever issues `GET` requests to `/api/v1/workflows` and `/api/v1/executions`. It never creates, updates or deletes anything in n8n. ## Step 2 — Create the connection in Odoo Open **n8n Connector ▸ Configuration ▸ Instances** and create a record. Key fields: | Field | What to enter | |---|---| | Name | A label for this server, e.g. *Production n8n*. Must be unique per company. | | Base URL | Your n8n server root, e.g. `https://n8n.example.com` (or `http://localhost:5678` for a local server — see *Allow internal host*). | | Authentication | *API Key (X-N8N-API-KEY)* — the only mode n8n's public API supports. | | API Key | The key copied in Step 1 (visible to administrators only). | | API Path | Leave the default `api/v1` unless your n8n server differs. | | Verify SSL | Keep on for production. Turn off only for self-signed test certificates. | | Allow internal host | Off by default. Turn on only to reach an n8n server on localhost or a private network (lowers the SSRF guard — see *Safety features*). | Then click **Test Connection**. It performs a lightweight `GET /api/v1/workflows?limit=1` to validate the key and reachability. A green *Connected* state means the API key and URL are correct. If it fails, the exact error is recorded on the form (*last connection error*) and in **Logs** (see *Troubleshooting*). Tip: use **Quick Setup** (button on the instance) to seed starter flows, default field mappings and a safety profile in one step. ## Step 3 — First import (dry-run, then live) New instances start with **Dry-run** ON. In dry-run, import jobs *simulate* writes: instead of creating records they produce **Validation Results** you can review under **n8n Connector ▸ Operations ▸ Validation Results**. This lets you confirm what *would* be imported before anything is written. To run a first import: 1. On the instance, click **Import Workflows** (and/or **Import Executions**). This enqueues jobs; it does not block the UI. 2. Jobs are processed by the **N8n Queue Processor** scheduled action (every minute), or immediately if you run it manually from **Operations ▸ Queue Jobs**. 3. Review **Validation Results** while still in dry-run. 4. When satisfied, open the instance, turn **Dry-run** OFF, and run the imports again to write the records for real. Imported records land in **n8n Connector ▸ Imported Data ▸ Workflows** and **▸ Executions**. Each carries its n8n id, so re-imports update the same record instead of duplicating it. Defaults: a workflow import pulls up to **100** workflows per run and an execution import up to **200** (the *Workflows import limit* / *Executions import limit* fields on the instance). The connector follows n8n's cursor pagination across pages automatically. ## Field mapping & customization The two n8n entities have no native Odoo counterpart, so the connector ships dedicated models (`n8n.workflow` / `n8n.execution`) and a built-in mapping that already populates the core fields (name, ids, active flag, node/trigger counts, tags, status, mode, finished, timestamps). You do not need to configure anything for a standard import. To customize: - **Field Mappings** (Configuration) let you map additional n8n payload fields to Odoo fields per entity (*workflow* / *execution*), with optional transforms and defaults. They are applied on top of the built-in mapping. Use **Generate suggested mappings** on the instance to seed the common ones, then adjust. - **Schema Fields** lists the discovered n8n fields per entity alongside the Odoo target fields. Run **Schema Introspection** on the instance to refresh it; it samples one live n8n record (falling back to the bundled mock when the API is unreachable) and flattens its shape so you can see the available paths. - **Execution Status Mappings** (Configuration) hold per-instance rules seeded on first successful connect. n8n execution statuses are normalized to *Success / Error / Running / Waiting / Unknown*; any status the mapping does not recognize is stored as *Unknown* so an unexpected value never breaks an import. ## Automation (scheduled actions) The module ships these scheduled actions (**Settings ▸ Technical ▸ Scheduled Actions**): | Scheduled action | Default | Purpose | |---|---|---| | N8n Queue Processor | every 1 min | Processes queued import jobs. | | N8n Reconciliation | every 15 min | Pulls recent remote ids for enabled entities and queues any that are missing locally or need a retry. | | N8n Maintenance | every 1 hr | Recovers stale/locked jobs and trims old jobs and logs. | | N8n Flow Scheduler | every 5 min | Runs scheduled import flows. | | N8n Flow Metrics | every 1 hr | Aggregates flow-run metrics. | | N8n Auto Recover | every 15 min | Reopens a tripped circuit breaker once the cooldown passes and no blocking validation issues remain. | Turn on **Auto import** / **Auto reconcile** per entity on the instance (*Auto import workflows*, *Auto import executions*, *Auto reconcile workflows*, *Auto reconcile executions*) to let the scheduled actions keep the imported data current hands-free. **Webhooks**: n8n does not push workflow/execution change notifications to third parties, so this connector is scheduled-pull only. A route exists at `/n8n/webhook` but it is intentionally inert — it always returns *501 Not Implemented* so nothing breaks on install. Keeping data current relies on the reconciliation schedule above, not on inbound webhooks. ## Safety features - **Dry-run mode** — simulate imports and review Validation Results before going live (field *Dry-run mode*, ON by default). - **Business validation profiles** — *Minimal / Standard / Strict* gate risky writes (field *Business validation profile*, default *Standard*). - **Safety profiles** — *Conservative / Balanced / Aggressive* presets set dry-run, validation, rollback, delete strategy and batch size in one click (field *Safety profile*, default *Balanced*). - **Resilient queue** — every import is a job with retry and backoff (fixed or exponential, base 1 min, cap 120 min by default) and a dead-letter state. - **Circuit breaker** — after repeated failures an instance auto-pauses (*Tripped*, default threshold 5 consecutive failures); the Auto Recover action reopens it after a 30-minute cooldown once no blocking issues remain. - **Rollback snapshots** — when enabled, imports capture a snapshot so you can undo a batch from **Operations ▸ Rollback Snapshots** (field *Rollback enabled*, ON by default). - **SSRF guard** — the connector refuses internal/loopback/private/link-local/ reserved hosts (including cloud metadata addresses) unless *Allow internal host* is explicitly enabled. ## Troubleshooting | Symptom | Cause and fix | |---|---| | Test Connection fails with 401 / 403 | Wrong, expired or revoked n8n API key. Re-create it under **Settings ▸ n8n API** (Step 1) and paste the new key into the **API Key** field. | | "n8n API key (X-N8N-API-KEY) is required" | The **API Key** field is empty. Paste the key from Step 1. The field is admin-only, so a non-admin user cannot see or set it. | | "...is not allowed because it resolves to the non-public address..." | Base URL points at localhost/a private or reserved IP. Enable *Allow internal host* on the instance (self-hosted/local n8n only). | | "the URL must start with http:// or https://" | The Base URL is missing its scheme. Enter the full root, e.g. `https://n8n.example.com`. | | SSL errors on Test Connection | Self-signed certificate. Use a valid cert, or turn off *Verify SSL* for testing only. | | "n8n rate limit reached" (HTTP 429) | n8n is throttling. The client already retries with backoff; lower the import limits or run imports less often if it persists. | | "n8n server error" (HTTP 5xx) | The n8n server returned an error. The client retries transient 5xx with backoff; if it persists, check the n8n server health and logs. | | "n8n resource not found" (HTTP 404) | The API Path is wrong or the public API is not enabled. Confirm the path is `api/v1` and that the n8n public API is turned on. | | Jobs stay in *Pending* | The Queue Processor is off or the instance is paused. Check **Scheduled Actions** is active and the instance is not *Paused*. | | Instance shows *Tripped* | Circuit breaker tripped after repeated failures. Fix the server/key; Auto Recover reopens it after cooldown, or click **Resume**. | | Nothing happens after Import | You are in **Dry-run**. Review Validation Results, then turn dry-run off and re-run. | | Executions have no linked Workflow | The parent workflow has not been imported yet. The link is resolved best-effort; import workflows first, then executions (or re-run the execution import) to populate it. | For anything else, **Operations ▸ Logs** records every API call, payload and error with a timestamp. ## Frequently asked questions **Which versions are supported?** Odoo 20.0 on the Odoo side. On the n8n side, any server exposing the public REST API at `/api/v1` with `workflows` and `executions` endpoints (self-hosted or Cloud). Validate your build with the bundled mock first. **Do I need an n8n server to evaluate it?** No. A mock n8n API ships inside, so you can install, explore and demo the full import flow before connecting a real server. **How does authentication work?** Create one n8n API key under **Settings ▸ n8n API** and paste it into the instance. The connector sends it as the `X-N8N-API-KEY` header on every request. No OAuth, no token exchange. **Does it change anything in n8n?** No. The connector is read-only: it only issues `GET` requests to list and fetch workflows and executions. Export to n8n is not supported. **Does it use webhooks for real-time updates?** No. n8n does not push workflow/execution change notifications to third parties, so the connector keeps data current on a schedule (the Reconciliation cron). The `/n8n/webhook` route exists but is inert and returns 501. **Is it safe to run against production data?** It only reads from n8n, and on the Odoo side dry-run is ON by default with validation and rollback snapshots. You decide when to write for real. **What support and refund policy do I get?** Every request is answered within 24 hours, setup help included. If you report a bug within 2 months of purchase and it is not resolved within 15 days, you are entitled to a full money-back refund. ## Data, privacy & limits - The connector **reads** workflows and executions from your n8n server and **writes** the corresponding Odoo `n8n.workflow` / `n8n.execution` records. It never writes to n8n. The API key and webhook secret are stored in admin-only fields. - **In scope today**: read-only import of workflows and executions, scheduled reconciliation, field mapping, schema introspection, dry-run, validation, rollback snapshots and a multi-step flow engine. - **Out of scope**: any write-back to n8n (creating/activating/running workflows), inbound change webhooks, and timestamp-based incremental list filtering on the n8n API (v1 lists by cursor pagination; reconciliation re-lists and queues the delta). ## Support & updates - Support: [support@bambooforge.dev](mailto:support@bambooforge.dev) — answered within 24 hours, setup help included. - Refund: report a bug within 2 months of purchase; if unresolved within 15 days, full refund. - Full source is included. Updates track the supported Odoo 20 / n8n public REST API v1 line. ## Upgrading & version compatibility This build targets **Odoo 20.0**. Each Odoo major series (16.0, 17.0, 18.0, 19.0, 20.0) has its own dedicated build of this module — always install the build that matches your Odoo version. Mixing a build with a different Odoo series is not supported. ### Patch upgrades (same series, e.g. 20.0.1.0.0 → later) 1. **Back up** your database and filestore first. 2. Replace the module folder with the newer build. 3. Restart Odoo with the module updated: ``` ./odoo-bin -c your.conf -u bambooforge_n8n_connector -d your_db ``` 4. Odoo applies any schema/data changes automatically. Your existing records and configuration are preserved. ### Cross-version migration (moving to a newer Odoo) Upgrading Odoo itself is a database migration handled by Odoo's standard upgrade tooling. When you migrate the database to the next Odoo series, install the matching build of this module for that series. Data created by this module carries over with the database migration. After any upgrade the module's scheduled actions resume on their normal cadence — no manual re-activation is required. ## Uninstallation You can remove this module at any time from **Apps → (this module) → Uninstall**, or from the command line. Uninstalling is clean and reversible by reinstalling — but note what is and is not deleted. ### What is removed - The module's own tables and every record in them (25 models, prefixed `n8n.*`) — this is the data this module created. - The menus, actions, views and reports this module installed. - Its scheduled actions (cron jobs) — they stop immediately on uninstall. - Connection records, credentials, field mappings, queue jobs and sync logs stored in Odoo. ### What is preserved - **Your remote platform is never touched.** Uninstalling only removes the Odoo-side connector; products, customers and orders on the external store/service are untouched. - Records already imported into standard Odoo models (e.g. contacts, products, sales orders) remain — they are ordinary Odoo records once created. - Attachments and chatter messages on standard records are kept. As always, take a database backup before uninstalling in production. ## Changelog ### 20.0.1.0.1 - Built for Odoo 20: record rules and access rights rewritten onto Odoo 20's single ir.access model, the screens rebuilt on Owl 3, and every icon moved to the icon set Odoo 20 ships. ### 20.0.1.0.0 Current release for Odoo 20.0. This build includes: - A two-way trigger bridge between Odoo 20 and n8n: Odoo record events -> HMAC-signed n8n webhooks (resilient queue), plus a secured inbound endpoint (HMAC + replay-guard + strict allowlist) and prebuilt trigger templates. Workflows/executions import, dry-run, auditable source. Feature additions and fixes ship as new builds on the Odoo Apps store; this page and the module's `version` reflect the current published release. Always keep the build matched to your Odoo series (see *Upgrading & version compatibility*). ## How we make sure it works Before every release, **75 automated checks** run against this app on Odoo 16, 17, 18, 19 and 20. Among them: - Workflow and execution bindings do not collide. - Field not in allowlist is dropped. - Inactive trigger does not fire. - Notify job posts signed body. - Lock claims pending then refuses second claim. Tested for real against a current n8n release: 4 workflows read through the Public API with 0 errors, and a workflow created through the API arrived in Odoo on the next sync. The complete list is in the source you receive.