Connecting the CRM to n8n

n8n connects to the CRM through two standard nodes: Webhook to receive CRM events, HTTP Request to read and write through API v1. Illizeo also provides a workflow template ready to import, which turns an incoming email into a follow-up task or a new contact. This article is intended for the people who build n8n workflows.

Before you start #

• The CRM module must be enabled. To receive events, your Illizeo subscription must include webhooks, and your n8n instance must be reachable over https on the public internet.
• To download the template: “CRM settings — View”. To create the event subscription: “CRM settings — Create” (see CRM webhooks).
• An API token, created in Settings › Manage Illizeo › API Tokens (see Creating and managing API tokens). For the template: Read and Write for “CRM — contacts”, Write for “CRM — activities”. To receive events: read access to the objects concerned.
• The token acts with the permissions and scope of the person who created it: for the template, “CRM contacts — View” and “Create”, “CRM activities — Create”.
• In n8n, create a credential of type Header Auth: name Authorization, value Bearer, a space, then your token.

Receiving CRM events #

1. In n8n, add a Webhook node, method POST, and copy its production URL (https).
2. In Illizeo, open Settings › CRM › Webhooks and integrations, click New webhook and create a subscription to that URL, with your token and the events you want. Copy the signing secret.
3. Activate the workflow in n8n: its production URL only listens while it is active.
4. Before processing a call, verify its signature: recompute the HMAC-SHA256 of <t>.<raw body> with the secret and compare it with the v1 value of the Illizeo-Signature header. To do so, keep the raw body in the Webhook node, and do the calculation in a Crypto or Code node.
5. Answer quickly with a 2xx code (immediate response from the Webhook node), then process. Ignore an id already processed: a retry carries the same one.

The content received, the events and the retry rules are described in CRM webhooks. The Send a test button on the subscription’s page sends a ping event to check the connection.

Reading and writing through the API #

An HTTP Request node calls the CRM’s API v1: choose authentication by generic credential, of type Header Auth, and the credential created above. The paths are those of the API (/v1/crm/accounts, /v1/crm/contacts, /v1/crm/opportunities, /v1/crm/activities), with the q search, modified_since and cursor pagination: see Importing, exporting and using the API. A list answers in data.items.

The “incoming email to draft record” template #

The template receives an email (sender, name, subject, text) and looks for its sender in the CRM: if known, it creates a follow-up task on their account; if unknown, it creates the contact. It has six nodes:

The node names, and the “Répondre : ” prefix of the task, are in French in the template: rename them if you wish.

1. In Illizeo, open Settings › CRM › Webhooks and integrations. In the Integrations card, under n8n, click Download the template: you get illizeo-crm-n8n-email-vers-fiche.json, with no secret and no token.
2. In n8n, open a new workflow and import the file (workflow menu, Import from File).
3. Attach your Header Auth credential to the three HTTP Request nodes.
4. Adapt the template to your rules (for example the task’s due date, or a next step for contacts with no account), then activate it.
5. Send the emails to process to the Webhook node, from your email tool or another workflow, with the from, from_name, subject and text fields.

Good to know #

• The “draft” is a real contact record, owned by the person who created the token: complete it afterwards in the CRM (account, job title, legal basis).
• The last name is required: without a sender name, the template uses the address as the name, to be corrected afterwards in the CRM. Creating the contact returns 409 DUPLICATES_FOUND if the record resembles an existing contact, until the body sends confirmer_doublon set to true. The address of a contact under objection gives a contact under objection.
• A contact with no main account, or whose account the token’s creator cannot read, does not receive a task: the “Rattaché à un compte ?” node stops the workflow. Attach the contact to an account in the CRM, or connect another step to the “false” output.
• The template builds its bodies with JSON.stringify: a double quote or a line break in the email’s subject or text goes through without making the body invalid. Build the fields you add in the same way.
• If your organisation submits a write to human approval, the API returns 202 without writing anything (see Getting records and sendings approved).
• To prepare a record from an email without a third-party tool, the CRM also has its forwarding address (see The CRM forwarding address).

FAQ #

The “tâche de suivi” node returns a 422 or 403 error. #

The body fails the API’s checks, which name the key concerned: a task requires an account (compte_id) and a due date (echeance_le, in YYYY-MM-DD format). The template sends both; if you changed the body, check that they are still there. A 403 error comes from permissions: the token must carry Write for “CRM — activities”, and its creator must have “CRM activities — Create”.

The workflow does not receive CRM events. #

Check that the workflow is active, that the subscription points to the Webhook node’s production URL, and open the subscription’s page in Illizeo: its delivery log shows what n8n answered.