Integration patterns with n8n

Overview

This page describes the main patterns we recommend when integrating n8n with HIPE. It is intended for both:

Architects and technical leads designing the overall integration.
Engineers building and operating the workflows in n8n.

All patterns share the same principles:

n8n runs inside your infrastructure (on‑prem or cloud).
Connectivity to HIPE happens over private, controlled networks (for example, via VPN).
The HIPE n8n node (@packitoo/n8n-nodes-hipe) is the primary interface to HIPE data and operations.

The authoritative list of supported modules and operations is maintained in the GitHub repository:
Module Readiness – n8n-nodes-hipe.

flowchart LR
  subgraph "Customer infrastructure"
    A["Internal systems (ERP, CRM, DB, files)"] <--> B["n8n"]
  end

  B -- "HTTPS API" --> C["HIPE"]
  C -- "Webhooks / events" --> B

Pattern 1 – API‑based integration (recommended default)

In this pattern, n8n communicates with HIPE via the HIPE node and API tokens.

When to use it
- Most new projects.
- When you want strong control over permissions and auditability.
- When you do not need complex SQL or direct database access.
How it works
- You create a HIPE access token in your HIPE environment.

See: Create an access token.

In n8n, you configure HIPE credentials using this token.
Workflows use the HIPE node to call modules such as Users, Companies, Projects, Imports, Exports, Corrugated, etc.
Typical use cases
- Sync internal users, companies, and projects with your CRM or ERP.
- Trigger actions in HIPE based on events in external systems.
- Drive imports/exports from and to HIPE.
Pros
- Simple to secure and audit.
- Versioned and maintained by HIPE/Packitoo.
- Works well with n8n’s retry and error‑handling features.
Considerations
- Subject to API‑level rate limits and payload sizes.
- Some advanced reporting use cases may still need database or export‑based access.

Pattern 2 – Direct database access to your systems (advanced, used in production)

In some projects, n8n connects directly to your own databases (for example, MySQL) inside your infrastructure. HIPE is still accessed only via its HTTP API from n8n.

When to use it
- Reporting, analytics, or data‑warehouse feeds where you need complex queries.
- High‑volume batch exports where API calls would be less efficient.
- Legacy integrations that already rely on database views or procedures.
How it works
- n8n runs inside your network, with VPN‑based access to your databases.
- You configure a database credential in n8n (for example, a MySQL node connection).
- Workflows read (and optionally write) data using SQL against those databases.
- The same workflows call HIPE through the HIPE node and API tokens.
Pros
- Maximum flexibility for queries and transformations.
- Efficient for bulk operations and reporting.
Considerations & recommendations
- Use a dedicated database account, preferably read‑only where possible.
- Do not expose your databases to the public internet; keep them behind VPN and firewalls.
- Coordinate closely with your internal data owners and, if relevant, HIPE support before writing directly to business‑critical tables.
- Consider using views or dedicated schemas to decouple your workflows from internal schema changes.

This pattern is already used in production by some customers, always inside a private, segmented network and with appropriate authentication.

Pattern 3 – Event and webhook‑driven workflows

In this pattern, HIPE emits events/webhooks which trigger n8n workflows.

When to use it
- You want near‑real‑time reactions to changes in HIPE (for example, new projects, status changes, reminders).
- You want to keep external systems in sync without polling.
How it works
- HIPE sends webhooks for subscribed events to an n8n webhook URL.
- An n8n workflow starts on each event, then calls back into HIPE (via the HIPE node) or other systems.
Typical use cases
- Notify CRM or ERP when a project reaches a certain stage.
- Trigger internal tasks or reminders in your own systems.
- Kick off exports or downstream ETL jobs.
Pros
- Event‑driven and efficient; no polling.
- Clear mapping from business events to workflows.
Considerations
- You need to expose the n8n webhook endpoint via a controlled entry point (for example, API gateway, reverse proxy) while keeping the main n8n UI behind VPN.
- You must manage webhook authentication and verification.

For the list of available events, see:
Events reference.

Pattern 4 – File‑based imports and exports

Many integrations can be implemented using files exchanged via HIPE imports/exports and orchestrated by n8n.

When to use it
- Existing processes already exchange CSV or flat files.
- You want a simple, auditable integration between HIPE and another system that also supports file‑based exchange.
How it works
- n8n retrieves or receives a file (from SFTP, object storage, email, etc.).
- The HIPE node uses Imports or Exports modules to push or pull data.
- n8n can transform the data before or after it flows through HIPE.
Pros
- Often easiest to implement when systems already exchange files.
- Natural fit for batch updates and scheduled jobs.
Considerations
- Not real‑time by nature (batch‑oriented).
- Requires clear agreements on file formats and schedules.

Choosing the right pattern

In practice, most customers end up with a combination of these patterns.

Start with Pattern 1 (API‑based) for most operational integrations.
Use Pattern 4 (file‑based) when you already have established CSV or flat‑file exchanges.
Add Pattern 3 (event/webhook) when you need near‑real‑time reactions to HIPE events.

If you are unsure which pattern best fits your context, we recommend:

Starting from the examples in the GitHub repository:
@packitoo/n8n-nodes-hipe examples
Talking with your HIPE contact so we can review your architecture and constraints together.

Data governance & identifiers

Reliable integrations depend on clear identifier mapping between HIPE and your systems.

Every main HIPE entity (for example, companies, users, projects) has an externalId field.
- This field is meant to store the identifier of the corresponding record in your source system (ERP, CRM, etc.).
For one‑way flows, it may be enough to set externalId when pushing data into HIPE.
For bidirectional syncs, it is mandatory to have a stable mapping in both directions:
- HIPE stores your system’s identifier in externalId.
- Your system must also store the corresponding HIPE identifier (or the value you use as externalId) in a dedicated column or custom field.

For any bidirectional integration, we must be able to persist a durable mapping between HIPE entities and your local entities. Without this, we cannot safely perform updates, avoid duplicates, or reconcile changes.

We recommend validating the ID mapping strategy as part of your project kick‑off before implementing workflows.