Automatisation n8n auto-hébergée pour les liens : de Docker aux webhooks

L'automatisation n8n auto-hébergée pour les liens signifie trois choses tournant sur des serveurs que vous contrôlez : une instance n8n dans Docker, un point d'entrée HTTPS public qui reçoit les événements de webhook Elido, et des appels sortants vers l'API Elido avec un jeton limité. Les événements de lien et de domaine arrivent signés, et les événements par clic sont sur la feuille de route. Vos workflows décident de la suite, et les journaux d'exécution ne quittent jamais votre infrastructure.

C'est toute l'architecture. Le reste de cet article, c'est la partie que les démarrages rapides sautent : comment faire passer les webhooks à travers un proxy inverse, comment vérifier la signature pour qu'un inconnu ne puisse pas déclencher vos workflows, ce que change le mode file d'attente, et quand n8n Cloud est honnêtement le meilleur choix. J'exécute cette configuration sur une seule petite VM, et les pièces mobiles tiennent sur un écran.

Si vous voulez aussi les liens eux-mêmes sur votre propre matériel, c'est un travail séparé et bien plus vaste. Le manuel d'auto-hébergement d'Elido sur k3s le couvre. Ici, Elido reste géré et seule la couche d'automatisation déménage en interne.

Pourquoi auto-héberger n8n pour l'automatisation de liens

La raison habituelle, c'est la donnée. Un workflow raccourcisseur d'URL n8n auto-hébergé voit chaque charge utile qu'il traite : l'URL de destination, les tags, parfois un nom de campagne qui en dit plus que vous ne voudriez, et le pays, l'appareil et le referrer si vous y intégrez des analyses de clics. Sur n8n Cloud, ces exécutions sont stockées sur les serveurs de quelqu'un d'autre sous les paramètres de rétention par défaut de quelqu'un d'autre. Auto-hébergées, elles vivent dans votre Postgres, dans la région que vous avez choisie.

Selon l'article 28 du RGPD, chaque sous-traitant qui touche des données personnelles a besoin d'un contrat et d'une place dans vos registres. Moins de sous-traitants, moins de paperasse. Si vos données marketing doivent déjà rester dans l'UE, le guide de résidence des données UE explique pourquoi la couche d'automatisation compte tout autant.

La deuxième raison, c'est la forme du coût. n8n Cloud tarifie par exécutions, et un déclencheur webhook actif ou un sondage d'analyse fréquent brûle vite des exécutions. Auto-hébergée, une exécution est une ligne dans une table et quelques millisecondes de CPU.

La troisième, c'est la portée. Une instance auto-hébergée vit sur le même réseau que votre base de données CRM ou votre outil de tickets interne, donc un événement de lien peut atterrir dans un système qui n'était jamais destiné à faire face à internet.

La pile Docker Compose

Une pile minimale d'automatisation de liens n8n docker a besoin de quatre services. Le propre guide Docker Compose de n8n est la référence ; voici la version dont je partirais pour du travail sur les liens, avec le mode file d'attente déjà activé pour ne pas avoir à migrer plus tard.

services:
  postgres:
    image: postgres:16
    environment:
      POSTGRES_USER: n8n
      POSTGRES_PASSWORD: ${PG_PASSWORD}
      POSTGRES_DB: n8n
    volumes: [pgdata:/var/lib/postgresql/data]

  redis:
    image: redis:7

  n8n:
    image: docker.n8n.io/n8nio/n8n
    env_file: .env.n8n
    ports: ["127.0.0.1:5678:5678"]
    depends_on: [postgres, redis]

  n8n-worker:
    image: docker.n8n.io/n8nio/n8n
    command: worker
    env_file: .env.n8n
    depends_on: [n8n]

volumes:
  pgdata:

Et le fichier d'environnement partagé :

DB_TYPE=postgresdb
DB_POSTGRESDB_HOST=postgres
DB_POSTGRESDB_USER=n8n
DB_POSTGRESDB_PASSWORD=change-me
EXECUTIONS_MODE=queue
QUEUE_BULL_REDIS_HOST=redis
N8N_ENCRYPTION_KEY=generate-a-long-random-string
N8N_WEBHOOK_URL=https://n8n.example.com/
N8N_PROXY_HOPS=1

Deux lignes comptent plus qu'elles n'en ont l'air. La clé de chiffrement doit être identique sur le processus principal et chaque worker, sinon les workers ne peuvent pas déchiffrer l'identifiant Elido et chaque exécution échoue avec une erreur d'authentification déroutante. Et le port 5678 est lié uniquement à localhost, parce que le proxy inverse est la seule chose qui devrait faire face à internet.

Appeler l'API Elido depuis n8n auto-hébergé

Les appels sortants n'ont besoin de rien au-delà de ce qui est livré avec n8n. Créez un identifiant Header Auth avec le nom Authorization et la valeur Bearer suivie d'une clé API du tableau de bord Elido, puis utilisez-la depuis le nœud HTTP Request intégré. n8n le chiffre au repos avec la clé du fichier d'environnement, ce qui est une raison de plus pour que cette clé corresponde partout.

Chaque route de lien est limitée à un espace de travail. Pour raccourcir une URL, envoyez un POST vers https://api.elido.app/v1/workspaces/{workspace_id}/links avec un corps JSON :

{
  "domain_id": 12,
  "destination_url": "{{ $json.url }}",
  "title": "Spring launch",
  "tags": ["n8n", "spring"]
}

Laissez slug de côté et Elido en génère un. Le domain_id est le domaine court sur lequel vit le lien ; un GET vers /v1/workspaces/{workspace_id}/domains liste les vôtres, et je coderais en dur l'ID dans le workflow plutôt que de le rechercher à chaque exécution. Un GET sur la même route de liens liste les liens, et PATCH /v1/workspaces/{workspace_id}/links/{link_id} change une destination ou des tags après coup.

Définissez un en-tête Idempotency-Key sur le POST, construit depuis quelque chose de stable dans l'élément déclencheur comme un ID de ligne. Si n8n retente le nœud après un délai d'attente, l'API rejoue la première réponse au lieu de créer un second lien. Le démarrage rapide API et SDK couvre le reste de la surface, et la page API et SDK est là si vous préférez déplacer une étape vers du code plus tard.

Il existe aussi un nœud communautaire packagé, n8n-nodes-elido, destiné à envelopper ces appels sous une forme plus conviviale. Il est publié sur npm (version 0.2.0), mais reste optionnel et, comme il ne s'agit pas d'un nœud vérifié, il s'installe uniquement sur n8n auto-hébergé, qui est précisément la configuration supposée dans cet article. Gardez la version HTTP Request comme référence. Si vous installez des paquets communautaires en mode file d'attente, rappelez-vous que la GUI ne s'installe que dans le conteneur principal ; les workers ne le voient jamais. À partir de n8n 2.21, la route d'installation par variable d'environnement corrige cela en réconciliant chaque conteneur au démarrage, bien qu'elle désinstalle tout ce qui n'est pas sur sa liste la première fois.

Faire passer les webhooks Elido à travers votre proxy inverse

Les événements circulent dans l'autre sens. Elido émet link.created, link.updated et domain.verified (entre autres) vers un point d'entrée que vous enregistrez sous Paramètres, Webhooks, et sur n8n auto-hébergé, ce point d'entrée est l'URL de production d'un nœud Webhook. Un événement click.created par clic est sur la feuille de route mais pas encore livré, donc pour l'instant les données de clic viennent d'un tirage planifié de l'API d'analyse. La liste complète des événements et les formes de charge utile sont dans la référence webhooks pour les événements de lien.

Derrière un proxy, n8n construit son URL de webhook depuis son propre protocole, hôte et port, ce qui signifie qu'il annoncera joyeusement http://localhost:5678/webhook/... à quiconque le demande. La page de configuration de proxy inverse est courte et mérite d'être lue en entier : définissez N8N_WEBHOOK_URL sur votre adresse publique, définissez N8N_PROXY_HOPS=1, et faites en sorte que le dernier proxy transfère X-Forwarded-For, X-Forwarded-Host et X-Forwarded-Proto. Les anciens guides disent WEBHOOK_URL ; les versions actuelles le lisent encore mais journalisent un avertissement de dépréciation.

Nginx, Traefik, ce que vous faites déjà tourner convient. Ce qui compte, c'est le TLS côté public et que le chemin /webhook/* atteigne n8n sans modification.

Un détail de timing m'a mordu. Elido attend dix secondes une réponse avant de compter une livraison comme échouée. Un workflow qui écrit vers une API de tableur lente puis répond peut dépasser cela, être retenté, et écrire la même ligne deux fois. Réglez le nœud Webhook pour répondre immédiatement et faire le travail après.

Si vous câblez ceci pour un client et voulez que le côté webhook soit géré pour vous, la page fonctionnalité webhooks montre ce à quoi vous pouvez vous abonner avant de construire quoi que ce soit.

Vérifier la signature avant que quoi que ce soit ne s'exécute

Une URL de webhook publique est une URL publique. Quiconque la trouve peut publier un faux événement et déclencher votre workflow, donc le premier nœud après le déclencheur devrait être une vérification de signature.

Chaque livraison Elido porte X-Webhook-Signature (valeur v1= plus un condensé hexadécimal), X-Webhook-Timestamp en secondes Unix, X-Webhook-Event et X-Webhook-Delivery. Le condensé est un HMAC-SHA256 sur l'horodatage, un point, et le corps de requête brut, keyé avec le secret whsec_ affiché une fois quand vous avez créé le point d'entrée.

Activez d'abord Raw Body sur le nœud Webhook. C'est l'étape que les gens sautent. Si vous hachez JSON.stringify($json.body) au lieu des octets exacts qu'Elido a envoyés, l'ordre des clés ou les espaces diffèrent et chaque signature échoue, et vous passerez une soirée convaincu que le secret est faux. Puis un nœud Code :

const crypto = require("crypto");
const item = $input.first();
const h = item.json.headers;
const raw = (await this.helpers.getBinaryDataBuffer(0, "data")).toString(
  "utf8",
);

const ts = Number(h["x-webhook-timestamp"]);
if (Math.abs(Date.now() / 1000 - ts) > 300) throw new Error("stale delivery");

const expected =
  "v1=" +
  crypto
    .createHmac("sha256", $env.ELIDO_WEBHOOK_SECRET)
    .update(`${ts}.${raw}`)
    .digest("hex");
const got = h["x-webhook-signature"] || "";
if (
  got.length !== expected.length ||
  !crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected))
) {
  throw new Error("bad signature");
}
return [{ json: JSON.parse(raw) }];

Le module crypto est disponible par défaut dans le nœud Code, donc aucune configuration supplémentaire n'est nécessaire là. La fenêtre de cinq minutes bloque les rejeux d'une requête capturée. Quand vous faites tourner le secret, Elido envoie aussi X-Elido-Signature-Previous pendant la période de grâce, donc vous pouvez accepter l'une ou l'autre clé pendant que vous mettez à jour la variable. Le guide de vérification des signatures de webhook propose une version de ce nœud qui vérifie les deux en-têtes, ainsi que le même contrôle en Node, Python et Go.

Mode file d'attente et nouvelles tentatives

Avec la vérification de signature en place, la question restante est ce qui se passe sous charge ou quand quelque chose est en panne. Deux systèmes de nouvelle tentative sont en jeu ici, et ils couvrent des échecs différents.

En mode file d'attente n8n, le processus principal reçoit le webhook, crée une exécution et remet son ID à Redis ; les workers le récupèrent. Une rafale d'événements s'empile dans la file d'attente au lieu de bloquer la réponse HTTP. Pour plus de volume entrant, vous pouvez ajouter des processeurs de webhook dédiés derrière un répartiteur de charge, bien que pour la plupart des charges de travail de liens, un processus principal et deux workers suffisent amplement.

Le côté Elido gère le cas où n8n est injoignable. Toute réponse non-2xx ou délai d'attente est retenté après 1, 5 et 15 minutes ; après trois tentatives, la livraison est marquée échouée et vous pouvez la réarmer depuis le tableau de bord. Cela couvre un redémarrage de conteneur ou un déploiement rapide. Cela ne couvre pas une panne de week-end, ce pour quoi j'associerais les webhooks à une réconciliation nocturne qui liste les liens via l'API, comme l'article webhooks contre sondage le soutient.

Utilisez X-Webhook-Delivery comme clé d'idempotence. Les nouvelles tentatives la réutilisent.

n8n auto-hébergé contre n8n Cloud : compromis honnêtes

Je préfère l'auto-hébergement pour ceci, mais j'ai vu des équipes le regretter. Voici la comparaison sans l'argumentaire de vente d'aucun des deux côtés.

La dernière ligne coupe dans les deux sens. Une petite VM est bon marché, mais une heure d'ingénieur sur une mise à jour cassée ne l'est pas, et n8n publie souvent. Si personne dans l'équipe ne possède la machine, Cloud avec le nœud HTTP Request et l'API REST d'Elido est l'option la plus sensée, et les recettes Make et IFTTT ou le guide Zapier montrent à quoi ressemble ce chemin géré sur d'autres plateformes.

Ce que je ne peux pas vous dire, c'est si votre délégué à la protection des données acceptera une machine auto-hébergée comme plus simple qu'un DPA fournisseur. Dans mon expérience, c'est généralement le cas, mais cela dépend de la qualité de gestion de la machine. Pour comment fonctionne le côté raccourcisseur du contrat, le guide RGPD pour les raccourcisseurs d'URL est le point de départ. Et si vous êtes prêt à câbler le premier workflow, obtenez un jeton API sur un espace de travail et pointez un nœud Webhook dessus.

À lire aussi sur le blog

• Auto-hébergement d'Elido sur k3s : le manuel - quand les liens doivent aussi vivre en interne.
• Webhooks pour les événements de lien - chaque type d'événement et forme de charge utile.
• Webhooks contre sondage pour le suivi des clics - pourquoi la réconciliation nocturne compte.
• Automatisation de liens courts avec Make et IFTTT - la voie low-code gérée.
• Raccourcisseur d'URL n8n - la configuration du nœud HTTP Request et trois workflows en détail.
• Vérifier les signatures de webhook - le corps brut, la fenêtre de rejeu et la rotation du secret dans quatre environnements d'exécution.