Intégration n8n Zendesk : nodes, identifiants et exemples de workflows

Le node Zendesk lit ou modifie des données dans Zendesk en tant qu'étape d'un workflow. La documentation de n8n regroupe ses opérations par ressource.

Un comportement surprend souvent. Quand vous utilisez Update Ticket et remplissez le champ Tag Names or IDs, la documentation de n8n indique que toute la liste des tags du ticket est remplacée : tout tag que vous n'incluez pas est donc supprimé. Cela suit la façon dont l'API Zendesk gère par défaut les mises à jour de tags. La documentation propose trois solutions de contournement : récupérer les tags actuels et les fusionner avec les nouveaux avant la mise à jour, utiliser le node HTTP Request avec la propriété additional_tags de Zendesk, ou appeler l'endpoint tags du ticket. Les deux dernières ajoutent des tags sans supprimer les existants.

Si le node ne prend pas en charge une opération dont vous avez besoin, utilisez le node HTTP Request, réglez Authentication sur Predefined Credential Type et choisissez votre credential Zendesk. La requête réutilise alors la même connexion que le node Zendesk.

Les nodes Zendesk et Zendesk Trigger utilisent le même credential, et n8n prend en charge deux méthodes d'authentification. Les deux nécessitent votre sous-domaine, c'est-à-dire la partie de votre URL Zendesk située entre https:// et .zendesk.com.

• Token API : dans l'Admin Center de Zendesk, ouvrez Apps and integrations, puis APIs, et activez l'accès par token pour l'API Zendesk. Ajoutez un token avec une description et copiez-le. Dans n8n, saisissez le sous-domaine, l'adresse e-mail avec laquelle vous vous connectez à Zendesk et le token.
• OAuth2 : dans l'Admin Center de Zendesk, créez un client OAuth sous Apps and integrations, puis APIs. Collez l'URL de callback OAuth de n8n dans le champ d'URL de redirection du client. Copiez l'identifiant unique du client dans Client ID dans n8n et son secret dans Client Secret, ajoutez le sous-domaine, enregistrez et connectez votre compte Zendesk.

Il existe deux façons de lancer un workflow n8n depuis Zendesk. Le node Zendesk Trigger lance un workflow quand des événements Zendesk correspondent aux conditions définies dans le node. Dans l'exemple de la documentation de n8n, il filtre les tickets dont le statut est Open, et le workflow s'exécute dès que vous l'activez.

L'autre solution consiste à construire la connexion vous-même. Dans l'Admin Center de Zendesk, allez dans Apps and integrations, puis Webhooks, créez un webhook, choisissez Trigger ou Automation comme méthode de connexion et faites-le pointer vers la Production URL d'un node Webhook de n8n. Ajoutez ensuite l'action « Notify webhook » à un déclencheur ou à une automatisation Zendesk et rédigez la charge utile, qui ne peut pas dépasser 16 000 caractères. Les conditions restent ainsi dans les règles métier de Zendesk, et vous choisissez exactement quels champs envoyer.

Si vous utilisez un webhook, vérifiez que les requêtes proviennent bien de Zendesk. Zendesk envoie deux en-têtes, X-Zendesk-Webhook-Signature et X-Zendesk-Webhook-Signature-Timestamp. La signature est base64(HMACSHA256(timestamp + body)), calculée avec le secret de signature du webhook, que vous pouvez afficher sur la page de détails du webhook ou obtenir via l'API. Recalculez-la dans votre workflow et rejetez les requêtes qui ne correspondent pas. Zendesk précise aussi qu'une même action peut appeler un webhook plus d'une fois : faites en sorte que le workflow puisse s'exécuter deux fois pour le même ticket sans dommage.

Le node Webhook peut répondre immédiatement, quand le dernier node se termine, ou via un node Respond to Webhook distinct. Pour les workflows plus longs, répondre immédiatement donne à Zendesk une réponse rapide pendant que le reste du travail se poursuit.

Voici un schéma courant, décrit étape par étape. Il montre comment les nodes s'articulent. Ce n'est pas une étude de cas TascaLab.

1. Déclenchement : un node Zendesk Trigger, ou un node Webhook alimenté par un déclencheur Zendesk qui s'active à la création d'un ticket. Envoyez au moins l'ID du ticket.
2. Récupération : un node Zendesk avec la ressource Ticket récupère le ticket complet, y compris l'objet, la description et les tags actuels.
3. Classification : un node Text Classifier trie le texte dans des catégories que vous définissez, comme facturation, problème technique ou remboursement. Chaque catégorie a un nom et une description qui aide le modèle. Par défaut, les éléments qui ne correspondent à aucune catégorie sont écartés : activez la branche Other pour les récupérer.
4. Mise à jour : un node Zendesk définit le groupe et les tags. Fusionnez d'abord les tags existants, ou ajoutez les tags via le node HTTP Request avec additional_tags, pour ne pas effacer les tags posés par les agents.
5. Notification : un node Slack publie la catégorie et un lien vers le ticket dans le canal de l'équipe.
6. Gestion des erreurs : envoyez les exécutions en échec vers une alerte, et attendez puis réessayez quand Zendesk renvoie une réponse 429.

Vous pouvez étendre ce schéma. Envoyez les tickets urgents dans un canal Slack distinct, ou recherchez l'organisation du client avec la ressource Organization avant de choisir un groupe.

Zendesk limite le nombre de requêtes API par minute selon l'offre. Sa documentation développeur indique ces limites par défaut pour les API Support et Help Center :

• Suite Team : 200 requêtes par minute.
• Suite Growth et Suite Professional : 400 requêtes par minute.
• Suite Enterprise : 700 requêtes par minute.
• Suite Enterprise Plus : 2 500 requêtes par minute.

L'add-on High Volume API porte une offre éligible à 2 500 requêtes par minute. Il remplace la limite de l'offre au lieu de s'y ajouter, et nécessite Suite Growth ou supérieur (ou Support Professional ou supérieur) avec au moins 10 sièges d'agent. Au-delà de la limite, Zendesk renvoie un HTTP 429 avec un en-tête Retry-After qui indique combien de secondes attendre. Certains endpoints ont leurs propres limites, plus strictes. Comptez les appels API effectués à chaque exécution et multipliez-les par votre volume de tickets en pointe. Les traitements en masse, comme l'ajout rétroactif de tags sur d'anciens tickets, risquent davantage d'atteindre la limite : traitez-les par lots et ajoutez des pauses.

n8n s'exécute en tant que n8n Cloud, une instance gérée que n8n exploite pour vous, ou en auto-hébergement sur votre propre machine ou infrastructure. Pour la plupart des installations auto-hébergées, la documentation recommande Docker, et elle recommande n8n Cloud si vous n'avez pas l'habitude d'administrer des serveurs. Quelle que soit la méthode de déclenchement, Zendesk doit pouvoir joindre votre instance n8n. Si une instance auto-hébergée se trouve derrière un reverse proxy, définissez N8N_WEBHOOK_URL sur son URL de base publique pour que n8n affiche les bonnes URL de webhook et que les services externes les enregistrent correctement. N8N_WEBHOOK_URL remplace WEBHOOK_URL, qui fonctionne encore mais est déprécié à partir de n8n 2.35.0.

TascaLab construit ce type d'automatisations Zendesk avec n8n, Make, des API et des webhooks, sur les outils que vous utilisez déjà. Les projets Ticket Routing & Categorization coûtent 690 €, et les projets Custom Automation à partir de 1 070 €. La plupart des mises en place prennent 1 à 3 semaines, et chaque projet comprend une documentation de base et 30 jours de support après le lancement. Vous pouvez commencer par un appel Health Check gratuit de 30 minutes.