Odoo n8n Bridge

Reusable webhook bridge for connecting Odoo Community with n8n workflows.

Overview

Odoo n8n Bridge is a reusable integration addon for Odoo Community 18.0 that standardizes how Odoo exchanges webhook traffic with n8n. It provides inbound webhook handling, outbound event dispatch, delivery logging, retry controls, and supporting documentation so teams can build automation workflows without rebuilding the plumbing for every project.

Why This Exists

Many Odoo automation projects need the same operational layer:

• authenticated inbound callbacks from n8n or external systems
• outbound business event delivery to webhook-based workflows
• auditable request and response history
• retry logic for transient failures
• a clean foundation that works without Odoo Enterprise dependencies

This repository packages that layer into a standalone addon and local development environment that can be reused across CRM, sales, accounting, onboarding, support, and middleware use cases.

Key Features

• Generic inbound webhook endpoint with shared_secret, bearer, api_key_header, hmac_sha256, and none authentication modes
• Outbound event subscriptions with payload templates and endpoint-specific retry controls
• Delivery attempt logging with redacted sensitive headers
• Company-aware access control with dedicated user, manager, and administrator roles
• Docker-based local environment for Odoo, PostgreSQL, and n8n
• Importable n8n workflow examples and a Postman collection for onboarding and testing

Architecture

flowchart LR
    A["Odoo Business Event"] --> B["Odoo n8n Bridge"]
    B --> C["n8n Webhook Workflow"]
    C --> D["External System / AI / Notification / API"]

    E["External System"] --> F["n8n Workflow"]
    F --> G["Odoo Bridge Inbound Endpoint"]
    G --> H["Odoo Record / Event Log"]

Loading

Repository Structure

• addons/odoo_n8n_bridge/: production addon code, views, security, demo data, tests
• n8n/workflows/: importable n8n examples
• docs/: architecture, setup, security, deployment, and roadmap
• scripts/: bootstrap, startup, reset, and validation scripts
• postman/: API collection for inbound endpoint testing
• .github/: issue templates, pull request template, and CI workflows

Quick Start

cp .env.example .env
docker compose up --build
docker compose exec odoo bash
python3 /opt/odoo/odoo-bin -c /etc/odoo/odoo.conf -d odoo -u odoo_n8n_bridge --stop-after-init

Odoo Setup

1. Start the stack with docker compose up --build.
2. Open Odoo at http://localhost:8069.
3. Enable developer mode and update the app list.
4. Install Odoo n8n Bridge.

n8n Setup

1. Start n8n from the same Docker stack at http://localhost:5678.
2. Import one of the workflows from n8n/workflows/.
3. Configure environment variables or credentials for the target Odoo base URL and webhook secret.
4. Activate the workflow after validating endpoint URLs and auth settings.

Endpoint Configuration

1. Open n8n Bridge > Configuration > Secrets.
2. Create a shared secret and click Generate or enter a controlled value.
3. Open n8n Bridge > Configuration > Endpoints.
4. Create an endpoint with:
   • Direction: both
   • Endpoint Type: generic
   • Code: crm_enrichment_callback
   • Auth Mode: shared_secret
   • Target URL: your n8n webhook URL for outbound flows

Event Subscription Examples

• res.partner write: sync contact updates to downstream automation flows
• res.partner create: trigger onboarding or enrichment pipelines
• Custom optional model subscriptions: extend the same pattern for crm.lead, sale.order, or account.move in deployments where those apps are installed

To create the first subscription:

1. Open n8n Bridge > Event Subscriptions.
2. Create a subscription on Contacts (res.partner) with event type write.
3. Choose the endpoint created above.
4. Leave sync_mode as queued for safer retries during setup.

API Endpoints

• POST /n8n/bridge/inbound/<endpoint_code>: authenticated inbound webhook entry point

See docs/api-contract.md for full request, response, and authentication mode details.

Security Model

• Secret values are restricted to bridge administrators and masked in the UI
• Delivery logs redact sensitive header values before persistence
• Inbound authentication is validated before payload parsing
• Company-aware record rules scope operational data for standard users and managers

See docs/security-model.md for the full design and hardening guidance.

Docker Setup

The local stack includes:

• postgres
• odoo
• n8n

The bootstrap script clones Odoo Community at the configured ODOO_VERSION, writes config/odoo.conf, and mounts the local addon path into the container runtime.

Inbound Test Command

curl -X POST "http://localhost:8069/n8n/bridge/inbound/crm_enrichment_callback" \
  -H "Content-Type: application/json" \
  -H "X-Bridge-Secret: your_shared_secret_here" \
  -d '{
    "event": "crm.lead.enriched",
    "model": "crm.lead",
    "record_id": 45,
    "external_id": "lead_123",
    "data": {"lead_score": 82},
    "metadata": {"workflow": "crm_lead_enrichment", "run_id": "manual-test"}
  }'

Outbound Test Flow

1. Import n8n/workflows/outbound_sale_order_event_example.json or generic_model_event_router.json.
2. Configure the workflow webhook URL on your outbound endpoint.
3. Update a contact in Odoo to trigger the bundled res.partner write subscription or create your own subscription.
4. Review n8n Bridge > Event Logs and Delivery Attempts.

Documentation Links

• Architecture
• Local Setup
• Security Model
• API Contract
• Event Subscriptions
• n8n Workflow Setup
• Deployment
• Roadmap

Roadmap

• Phase 2: inbound record update allowlists, replay protection, payload builder
• Phase 3: dead-letter queue, exponential backoff, rate limiting
• Phase 4: queue integration, observability, vault-backed secrets

Version Notes

• 17.0: XML view syntax and mail.thread usage remain close; re-test settings inheritance and cron ids.
• 18.0: primary target in this repository.
• 19.0: verify any framework changes around settings views, list tags, and HTTP controller request APIs before release.

License

LGPL-3.0. See LICENSE.

Maintainer

Maintained by Omni Academy Consulting & Technologies.

Contributing

See CONTRIBUTING.md.