@cypherlenn/n8n-nodes-evo-crm

n8n community nodes for EVO CRM – a German sales CRM (setter → appointment → closer → back office)
with leads, contacts, opportunities, activities, tasks, appointments, email/SMS/WhatsApp sending,
templates, sequences and an event log with signed webhooks.

The package contains:

• EVO CRM – an action node (also usable as an AI agent tool) for the EVO CRM REST API v1.
• EVO CRM Trigger – starts a workflow for any event of the CRM (signed webhooks, created and
  removed automatically).
• EVO CRM API credentials (API key).

Not to be confused with n8n-nodes-evocrm. That is an unrelated package for "Evolution API /
EvoCRM". This package (@cypherlenn/n8n-nodes-evo-crm) is for EVO CRM.

n8n is a fair-code licensed
workflow automation platform.

• Installation
• Credentials
• Operations
• Trigger
• Usage notes
• Example workflows
• Compatibility
• Development
• Deutsch

Installation

n8n (self-hosted or cloud with community nodes enabled): Settings → Community Nodes → Install,
enter @cypherlenn/n8n-nodes-evo-crm, confirm the risk notice and install. See the
n8n community nodes guide.

Manual installation (self-hosted):

mkdir -p ~/.n8n/nodes && cd ~/.n8n/nodes
npm install @cypherlenn/n8n-nodes-evo-crm
# restart n8n

With Docker, run the same inside the container (/home/node/.n8n/nodes) or mount that folder, then
restart the container. A local tarball (npm pack) can be installed the same way:
npm install /path/to/cypherlenn-n8n-nodes-evo-crm-0.6.0.tgz.

Credentials

1. In EVO CRM open Einstellungen → KI & API → API-Schlüssel and create a key. It is shown exactly
   once and looks like evo_live_…. Creating keys needs the permission "API-Schlüssel nutzen"
   (api.use; team leads, managing directors, owners/admins by default).
2. In n8n create credentials EVO CRM API:
   • Base URL – the address of your CRM without /api/v1, e.g. https://crm.example.com.
   • API Key – the evo_live_… key.
3. Test calls GET /api/v1/me.

The key acts with the permissions and data scope of its owner – a team lead only sees their team,
a managing director everything. Sensitive fields (IBAN, account holder, date of birth) are never
available through the API. Two-factor authentication does not apply to API keys, so treat keys like
passwords and use one key per integration.

Operations

Dropdowns are loaded live from the CRM: lead statuses, pipelines and stages, users (incl. "Me"), call
results, email/SMS/WhatsApp templates and template parameters, mailboxes, sequences, tags, saved views
and custom field keys. Every dropdown also accepts an ID via expression.

All "Get Many" operations support Return All (follows next_cursor while has_more) or a
Limit. Every item of a list becomes its own n8n item.

Trigger

EVO CRM Trigger registers a webhook subscription in the CRM when the workflow is activated
(POST /api/v1/webhook, name n8n: <workflow name>) and removes it on deactivation.

• Events: multi-select loaded from GET /api/v1/event_type. Values are object_type:action
  (e.g. lead:created, opportunity:won, activity.call:created), object_type:* for every action of
  a type, activity.*:* for every timeline entry and * for all events.
• Output: one item per delivery – the event as in GET /event/{id} (id, object_type,
  action, object_id, lead_id, user_id, source, changed_fields, data, previous_data,
  date_created …) plus webhook: { subscription_id, event_id, delivery_id }.
• Signature: every delivery carries EVO-Signature: t=<unix>,v1=<hex> (HMAC-SHA256 over
  "<t>.<raw body>" with the whsec_… key). The trigger verifies it with a 5-minute tolerance and
  answers forged/old requests with 401 (Options → Verify Signature, on by default). The key is
  stored in the workflow's static data; if it got lost, deactivate and activate the workflow.
• Ignore Test Events: skip deliveries of "Test senden" in the CRM (webhook:test).

Requirements and limits:

• The API key owner needs "API und Webhooks verwalten" (api.manage).
• The webhook URL must be public https (no localhost, no private networks). Run n8n behind a public
  https address (WEBHOOK_URL) or a tunnel.
• n8n's test URL and production URL each create their own subscription (the test one is named
  … (test) and removed when listening stops).
• The CRM allows at most 20 subscriptions per organisation and 50 object types per subscription.
• Deliveries are retried up to 21 times over about three days; after 20 failures in a row the CRM pauses
  the subscription. Re-activating the workflow resumes it.
• Order is not guaranteed; deduplicate with webhook.event_id and sort by date_created.

View trigger

EVO CRM View Trigger checks a saved view ("Ansicht") regularly and starts the workflow for every lead,
contact or opportunity that entered (or left) the view, e.g. "leads with status interested and no
appointment". Choose the record type and the view from the list; Trigger On: entered, left or both.

• The first poll after activation only remembers the records currently in the view; afterwards every change
  is reported once, with the full record in data (option Include Details).
• A record that leaves the view and comes back later triggers again. With the option Only Once per Record
  each record triggers at most once (per entered/left); the trigger then remembers up to 20,000 reported
  records per event.
• Poll Times: every minute is the shortest preset; a custom cron such as */30 * * * * * checks every
  30 seconds.
• Records also enter a view without being changed (time-based filters like "last contact more than 7 days
  ago"); the polling catches these too. Views with more than 20,000 records are rejected.
• The test run in the editor ("Fetch Test Event") returns the newest records of the view.

Output per record: event (entered/left), object_type, object_id, saved_view_id,
saved_view_name, date, data.

Usage notes

• IDs are prefixed (lead_…, con_…, opp_…, act_…, tsk_…, apt_…, tmpl_…, wat_…);
  people are UUIDs, me means the key owner.
• Records (lead, contact, opportunity, company, appointment, task, templates) are picked From List
  (searchable, live from the CRM) or By ID; expressions work in both. In the CRM every list with IDs
  needed here has Copy ID in its three-dot menu.
• Opportunity value is in cents (150000 = 1,500.00 €).
• Dates: date/time fields without time zone are read in the workflow time zone and sent as UTC.
• Custom fields (also the fields of a custom activity): choose the field; for choice fields the value
  is a list of the options (Option / Options), otherwise text. As text: options by name, dates as
  YYYY-MM-DD, booleans as true/false, people as me, user ID or email. Empty value = clear the
  field. Several multi-select options as text: comma-separated or JSON array (["Strom","Gas"]).
• Idempotency-Key (Request Options of every write operation): with the same key the CRM answers a
  repeated request within 24 hours with the stored result instead of creating or sending again – ideal
  for Retry On Fail. Use a value unique per item and run, e.g.
  {{ $execution.id }}-{{ $runIndex }}-{{ $itemIndex }}.
• Errors show the German message of the CRM, the code (validation_error, not_found,
  precondition_failed …), field errors and the request ID. 429/503 with a short Retry-After are
  retried automatically. With Continue On Fail the error becomes an item (error, description,
  httpCode).
• Sending vs. logging: Email → Send, SMS → Send and WhatsApp → Send … really send (blocklist,
  limits, consent and the WhatsApp 24-hour window apply). Activity → Log Email/SMS only adds a
  timeline entry.

Example workflows

WhatsApp: text if the window is open, otherwise a template

1. EVO CRM Trigger – event appointment:created.

2. EVO CRM – WhatsApp → Get Recipients, Lead ID {{ $json.lead_id }}.

3. IF – {{ $json.window_open }} is true.

   • true → EVO CRM – WhatsApp → Send Text, Lead ID from the trigger, To {{ $json.e164 }}.
   • false → EVO CRM – WhatsApp → Send Template, template termin_bestaetigung, To
     {{ $json.e164 }}, parameter body.1 = {{ $json.contact_name }}.

   Tip: Get Recipients returns one item per number; keep only the first one (e.g. Limit node) or filter
   on is_primary before the IF.

New lead → task for the owner

1. EVO CRM Trigger – event lead:created.
2. EVO CRM – Task → Create, Title Erstkontakt: {{ $json.data.display_name }}, Additional Fields:
   Lead ID {{ $json.object_id }}, Assigned To (expression) {{ $json.data.owner_id || 'me' }},
   Due Date {{ $now.plus(1, 'hour') }}.

Won deal → hand-over email from a template

1. EVO CRM Trigger – event opportunity:won.
2. EVO CRM – Email → Send, To backoffice@example.com, Content Template, Additional Fields:
   Opportunity ID {{ $json.object_id }}, Lead ID {{ $json.lead_id }}, Request Options:
   Idempotency Key won-{{ $json.object_id }}.

Website form → lead with contact

Webhook/Form → EVO CRM – Lead → Create with Contacts (name, email, phone) and custom fields
(e.g. evo_jahresverbrauch_kwh).

Compatibility

• n8n 1.x and later (community node API version 1, strict mode). Built and type-checked against
  n8n-workflow 2.16.
• No runtime dependencies (n8n-workflow is a peer dependency).
• Requires an EVO CRM with REST API v1. The send and template endpoints (email/SMS/WhatsApp, templates,
  /event_type) need a current CRM version; with an older CRM the trigger falls back to a built-in
  event list.

Development

npm install
npm run build      # n8n-node build → dist/
npm run lint       # n8n-node lint (community node rules)
npm test           # vitest (signature, events, pagination, mapping, execute, trigger)
npm run typecheck  # tsc incl. tests
npm run dev        # n8n with the node linked, http://localhost:5678
npm pack           # cypherlenn-n8n-nodes-evo-crm-<version>.tgz

Publishing to npm

Published by hand from this folder (no GitHub release workflow; prepublishOnly builds and tests first):

npm login
npm version patch   # only for later releases: 0.1.0 → 0.1.1 (also update CHANGELOG.md)
npm publish         # account with a passkey: no --otp, npm opens the browser confirmation

Self-hosted n8n installs unverified community packages without npm provenance. Listing as a verified
node on n8n Cloud would additionally need an author email, a homepage and publishing via GitHub
Actions with provenance (npm run lint reports the missing package fields).

Deutsch

@cypherlenn/n8n-nodes-evo-crm verbindet n8n mit dem EVO CRM (REST API v1). Nicht verwechseln mit dem
fremden Paket n8n-nodes-evocrm (Evolution API).

Installation: In n8n Settings → Community Nodes → Install und @cypherlenn/n8n-nodes-evo-crm eingeben.
Selbst gehostet alternativ npm install @cypherlenn/n8n-nodes-evo-crm in ~/.n8n/nodes und n8n neu starten.

Zugang: Im CRM unter Einstellungen → KI & API → API-Schlüssel einen Schlüssel (evo_live_…)
anlegen und in n8n als Credential „EVO CRM API" mit der CRM-Adresse (ohne /api/v1) hinterlegen. Der
Schlüssel arbeitet mit den Rechten und dem Datenumfang seiner Inhaberin; sensible Felder (IBAN …) gibt
es über die API nie.

Knoten „EVO CRM": Leads, Kontakte, Opportunities, Unternehmen, Aktivitäten (Notiz, Anruf mit
Gesprächsergebnis, E-Mail-/SMS-/Meeting-Eintrag, eigene Aktivität), Aufgaben, Termine, Versand von
E-Mail/SMS/WhatsApp, Vorlagen (E-Mail, SMS, WhatsApp), Tags, Sequenzen, Ereignisse, eigene Felder und
Konfiguration (Pipelines, Phasen, Lead-Status, Gesprächsergebnisse, Personen). Auswahllisten kommen live
aus dem CRM; Datensätze (Lead, Kontakt, Opportunity, Unternehmen, Termin, Aufgabe, Vorlagen) wählst du
From List (Suche) oder By ID, bei eigenen Feldern und Feldern eigener Aktivitäten erscheinen die
Optionen von Auswahlfeldern als Liste. IDs kopierst du im CRM über das Drei-Punkte-Menü („ID kopieren“).
Opportunity-Werte in Cent. Datums-/Zeitfelder ohne Zeitzone gelten in der Zeitzone des
Workflows. Für sichere Wiederholungen unter Request Options einen Idempotency-Key setzen, z. B.
{{ $execution.id }}-{{ $runIndex }}-{{ $itemIndex }}.

Knoten „EVO CRM Trigger": Beim Aktivieren legt der Knoten ein Webhook-Abo an (n8n: <Workflow>),
beim Deaktivieren löscht er es. Ereignisse als objektart:aktion, objektart:* oder * (alle). Jede
Zustellung wird über die Kopfzeile EVO-Signature geprüft (5 Minuten Toleranz, abschaltbar).
Voraussetzungen: Recht „API und Webhooks verwalten" (api.manage), öffentliche https://-Adresse von
n8n, höchstens 20 Abos je Organisation (Test- und Produktiv-URL von n8n zählen je als eigenes Abo).

Knoten „EVO CRM View Trigger": fragt eine gespeicherte Ansicht regelmäßig ab (Polling) und startet den
Workflow für jeden Lead, Kontakt bzw. jede Opportunity, die neu in die Ansicht kommt (oder sie verlässt). Art
und Ansicht wählst du aus der Liste. Der erste Lauf merkt sich nur den aktuellen Stand, danach meldet er jede
Änderung einmal mit dem vollständigen Datensatz. Kommt ein Datensatz später erneut in die Ansicht, löst er
wieder aus; mit der Option Only Once per Record höchstens einmal. Jede Minute ist das kürzeste Raster; mit eigenem Cron
*/30 * * * * * alle 30 Sekunden. Auch zeitabhängige Filter („letzter Kontakt vor mehr als 7 Tagen“) werden
erkannt; Ansichten über 20 000 Datensätze lehnt der Knoten ab.

Beispiel: Termin angelegt → WhatsApp-Empfänger abrufen → Fenster offen? Dann Text senden, sonst
die freigegebene Vorlage „termin_bestaetigung".

License

MIT